Get started

Headless React form primitives. useFormControl wires any custom input into a typed form context; <Form> (Web) or <NativeForm> (React Native) collects values; validation rules emit localized error messages. No Formik ceremony, no react-hook-form ref management — just hooks that read and write to a shared form context.

v4 (major). Form and NativeForm are now function components (forwardRef) built over a plain, React-free FormEngine class — the engine instance is what a ref to the form gives you. Ids are SSR-safe via React’s useId(). The old abstract BaseForm React component is now a deprecated alias for FormEngine (kept through v4, removed in v5). See migration notes at the end.

Highlighted features

Headless controls via `useFormControl`

Build any input shape — text, checkbox, radio, multi-value — by reading value, changeValue, error from the hook. Your component stays in charge of rendering.

Composable validation rules

rules: [requiredRule, emailRule] — combine built-ins or write your own. Error messages render through @mongez/localization (six locales ship: en, ar, fr, es, it, de).

Dot-notation names

name="user.firstName" auto-nests into values.user.firstName on submit. No flat-key gymnastics for nested forms.

Smart submit-button state

useSubmitButton exposes isSubmitting, disabled, isDirty — drop into your button without prop-drilling form state. (For the full snapshot use useFormState().)

Web + React Native

<Form> renders a real HTML form; <NativeForm> renders a fragment and submits programmatically. Same hooks, same validation, same API.

Form lifecycle events

Async validation that gates submit

A rule may return a Promise<ReactNode> — the engine awaits it before submitting, while sync rules stay synchronous. isValidating exposes the in-flight state.

Standard Schema interop

<Form schema={...}> validates the whole form on submit with zod / valibot / @warlock.js/seal — zero runtime dependency, with onSubmit values fully typed from the schema.

Install

npm install @mongez/react-form
# or: yarn add @mongez/react-form
# or: pnpm add @mongez/react-form

Peer dep: react >= 18. Runtime deps install transitively: @mongez/events, @mongez/localization, @mongez/supportive-is, @mongez/reinforcements.

Quick peek

import { Form, useFormControl, requiredRule, emailRule } from "@mongez/react-form";

function TextInput(props) {
  const { value, changeValue, error, otherProps } =
    useFormControl({ ...props, rules: [requiredRule, emailRule] });
  return (
    <>
      <input value={value} onChange={(e) => changeValue(e.target.value)} {...otherProps} />
      {error && <span>{error}</span>}
    </>
  );
}

<Form onSubmit={({ values }) => api.signup(values)}>
  <TextInput name="email" type="email" required />
  <button type="submit">Sign up</button>
</Form>

Wrap your own input around useFormControl, drop it inside <Form>, get typed values on submit.

Full setup steps

1. Register validation translations (one-time, at app entry)

Validation rules emit error messages through @mongez/localization. The translation bundles must be registered under the validation namespace before any form mounts. Do this once at the root of the app (typically src/main.tsx or App.tsx):

import { extend } from "@mongez/localization";
import {
  enValidationTranslation,
  arValidationTranslation,
} from "@mongez/react-form";

extend("en", { validation: enValidationTranslation });
extend("ar", { validation: arValidationTranslation });

Six locales ship: en, ar, fr, es, it, de. Register only those you need.

If this step is skipped, validation still runs but errors appear as raw translation keys (e.g. validation.required) instead of human-readable text.

2. Pick the right form component

Web → import Form from @mongez/react-form. Renders an HTML <form> element. Submits via the standard browser submit event.
React Native → import NativeForm from @mongez/react-form. Renders a Fragment by default (no host element). Submission is always programmatic.

Both expose the same API — the only differences are the rendered output and how submit is triggered.

3. Minimal first form (Web)

import { Form, useFormControl, requiredRule, type FormControlProps } from "@mongez/react-form";

function TextInput(props: FormControlProps) {
  const { value, changeValue, id, error } = useFormControl({
    rules: [requiredRule],
    ...props,
  });

  return (
    <>
      <input id={id} value={value} onChange={(e) => changeValue(e.target.value)} />
      {error && <span style={{ color: "red" }}>{error}</span>}
    </>
  );
}

export default function App() {
  return (
    <Form onSubmit={({ values }) => console.log(values)}>
      <TextInput name="firstName" required />
      <TextInput name="lastName" />
      <button>Submit</button>
    </Form>
  );
}

The name prop on each TextInput becomes the key in the submitted values object. Dot notation (user.firstName) is supported and produces nested objects.

4. Verify the baseline

After completing steps 1–3, you should be able to:

Mount the form, type into both inputs, click Submit.
See the values object logged with both names.
Submit with an empty first name and see the localized “This input is required” error rendered inline.

If any of those fail, the likely cause is one of:

Validation translations not registered → errors show as validation.required text.
name prop missing on an input → it won’t be collected into values.
<button> placed outside the <Form> → click won’t trigger form submission.

5. SSR is safe by default (v4); pass a stable `id` when you need a deterministic one

v4 derives the <Form> wrapper id from React’s useId() when you omit id, so the rendered <form id="form-<react-id>"> attribute matches between the server render and the client hydration — no hydration mismatch, no manual id required. (In v3 the wrapper fell back to Math.random(), which differed across the two passes; that’s fixed.)

You still want an explicit, stable id whenever you need the form’s identity to be predictable rather than auto-generated:

<Form id="signup" onSubmit={({ values }) => api.signup(values)}>
  <TextInput name="email" type="email" required />
  <SubmitButton>Sign up</SubmitButton>
</Form>

Rules of thumb:

Pass an id when you target the form in tests, styles, or analytics — useId() produces opaque values like form-:r3:, while id="signup" renders the stable form-signup.
Keep an explicit id unique on the page. The id drives the engine’s event prefix (form.<id>), so two forms sharing an id would cross-wire their events.
Inputs never need an id. A control’s id is derived from its name (input-<name>), already deterministic on both server and client.

6. The engine behind the form (`FormEngine`)

A ref to <Form> / <NativeForm> resolves to the FormEngine instance (typed as FormInterface) — a plain, React-free class that owns registration, validation, value collection, dirty tracking, events, hydration, and the submit pipeline:

import { Form, type FormInterface } from "@mongez/react-form";

const formRef = useRef<FormInterface>(null);

<Form ref={formRef} onSubmit={({ values }) => api.save(values)}>
  {/* ... */}
</Form>;

// later, imperatively:
formRef.current?.fill({ email: "a@b.co" });
formRef.current?.reset();

You rarely instantiate FormEngine yourself — the function components do it via useFormEngine. The deprecated BaseForm export is now just an alias for FormEngine; replace extends BaseForm usage with the function-component + engine pattern.

Migrating from v3

Form / NativeForm are function components now. If you held a ref, its type changed from the old BaseForm class instance to FormEngine (both satisfy FormInterface, so most code is unaffected).
BaseForm is deprecated. It re-exports FormEngine. Subclassing it as a React component no longer works — subclass FormEngine and render a thin function component (mirror useFormEngine) for custom renderers.
Drop manual id workarounds for SSR. The useId()-based default already fixes the v3 hydration mismatch.
form.submitting(false) is optional for awaited submits. If onSubmit returns a Promise, the engine clears the submitting state when it settles. See Submit button.
Everything else — useFormControl, rules, events, dot-notation names, useForm, useSubmitButton — keeps the same surface, plus new hooks (useFieldArray, useWatch) and new engine methods (fill, setValues, setErrors).

Where to go next

Create form control — patterns for text inputs, checkboxes, radios, multi-value controls, a11y prop bags, custom validation
Form events — change, submit, validation, dirty, reset lifecycle hooks
Submit button — useSubmitButton, smart submit state, awaited-submit auto-clear
Validation rules — built-in rules, async validation that gates submit, writing custom ones
Standard Schema validation — <Form schema>, per-field schema, type inference with zod / valibot / seal
Form hydration — values prop, form.fill / setValues / setErrors, defaultValue as reset baseline
Field arrays — useFieldArray for dynamic repeated rows
Watching values — useWatch for dependent fields and conditional UI
React Native usage — switching from Form to NativeForm
Recipes — common patterns