@formhaus/core
Framework-free engine for JSON form definitions: field state, validation, conditional visibility, repeatable groups, multi-step navigation and branching routes. No runtime dependencies and no UI. Part of Formhaus. For rendering, use @formhaus/react or @formhaus/vue.
Install
npm install @formhaus/core
Requires Node 22.12 or later. ESM; require() works too.
Usage
import { FormEngine, type FormDefinition } from '@formhaus/core';
const definition: FormDefinition = {
id: 'contact',
title: 'Contact Us',
submit: { label: 'Send' },
fields: [
{ key: 'name', type: 'text', label: 'Name', validation: { required: true } },
{ key: 'email', type: 'email', label: 'Email', validation: { required: true } },
],
};
const engine = new FormEngine(definition);
engine.setValue('name', 'Jane');
engine.validate();
// { email: 'This field is required' }
engine.setValue('email', '[email protected]');
engine.getSubmitValues();
// { name: 'Jane', email: '[email protected]' }
Entry points
| Import | Contents |
|---|---|
@formhaus/core | FormEngine, checkDefinition(), types |
@formhaus/core/server | validateSubmission() for untrusted payloads, also as server.iife.js |
@formhaus/core/cloud | Client for Formhaus Cloud: fetchForm(), createSubmitter(), createChallengeFrame() |
@formhaus/core/i18n | Message and label catalogs, overlays, translation keys |
@formhaus/core/fix | suggestFixes(), applyFix(), fixAll() |
@formhaus/core/fields | Helpers for custom field components: fieldState(), scaleView(), fromDate(), toDate() and others |
@formhaus/core/research | Opt-in survey features: research for random option order |
@formhaus/core/schema | schemaValidate() and schemaParse() for Zod, Valibot, ArkType and other Standard Schema libraries |
@formhaus/core/dirty | trackDirty() for unsaved changes |
@formhaus/core/style.css | Optional baseline styles with --fh-* theme tokens |
@formhaus/core/schema.json | JSON Schema of the definition |
@formhaus/core/internal holds code shared by @formhaus/react and @formhaus/vue. It is not a public API and has no semver guarantee: any release can change it. Do not import it.
Network
Only the /cloud entries make network requests.
@formhaus/core/cloudcallshttps://api.formhaus.cc, or theapiBaseyou pass, and loads a challenge frame fromhttps://formhaus.cc.- Every other entry makes no network requests.
Features
- Field types, validation rules,
show/showAnyconditions, sections and repeatable groups. See fields and validation. - Multi-step forms with lifecycle hooks, async step validation and branching routes.
goToStep(id)opens a step for URL routing: if the step can't be opened, the form opens the previous available step and reports it. - Server-side validation against the same definition.
- Form events: pass
onFormEventand callstart()to getform_viewed,step_viewed,field_shown,form_submit_succeededand more. - Granular subscriptions:
subscribe(),subscribeField(),subscribeStructure()andsubscribeValues(). - Translations through catalogs and overlay files.
- Definition checks and JSON Patch fix suggestions through
checkDefinition()and@formhaus/core/fix. - Formhaus Cloud: hosted endpoint, submissions, files and bot check.
FormhausFormin@formhaus/react/cloudand@formhaus/vue/cloudrenders a published form. - Theming:
import '@formhaus/core/style.css', then override--fh-*custom properties. A dark theme is on withdata-fh-theme="dark". - Claude Code skill and MCP server to generate and check definitions.
Docs
License
MIT