Skip to content
forge logoForgeState
Framework-neutral form and field state with nested handles, flat validation issues, and explicit integration helpers.
Version
v26.11.20
Size
3.9 KB gzip
BrowserNode ≥22SSRDeno
createFormtoPlainValues

Why Forge? ​

Forge owns form state without owning rendering or validation timing. Nested field handles keep access typed, flat validation issues compose across arrays and unions, and Forge-owned validation and persistence operations settle on cancellation.

Quick Start ​

ts
import { createForm } from '@vielzeug/forge';

const form = createForm({
  initialValues: { email: '', profile: { name: '' } },
  validate: (values) => (values.email.includes('@') ? undefined : [{ path: ['email'], message: 'Invalid email' }]),
});

form.field('profile').field('name').set('Ada');
const result = await form.validate();
FeatureForgeLocal component state
Bundle size3.9 KBn/a
Nested typed fieldsManual
Flat validation issuesManual
Abortable validationManual
Framework-neutralVaries
Zero third-party dependencies

Use Forge when several fields need coordinated validation, submission, dirty/touched state, nested updates, or explicit persistence.

Use local state when a form has only one or two fields and no shared validation lifecycle.

Installation ​

sh
pnpm add @vielzeug/forge

Features ​

  • createForm(): deeply readonly form state with structural sharing and cloned dates
  • field().field(): typed nested field handles
  • patch(): shallow top-level merge without spread casts
  • normalize + toPlainValues(): hold domain-model classes in form state
  • Flat { path, message } validation issues
  • Explicit validate() and submit() timing
  • /dom: optional element binding
  • /schema: validator-agnostic Standard Schema adapter
  • /persist: explicit key/value draft persistence
  • /form-data: browser submission serialization

Documentation ​

See Also ​

  • Spell: Standard Schema-compatible validation.
  • Vault: durable typed storage for drafts.
  • Assay: DOM test helpers for form interaction.