Form Builder

Introduction

The OGMF form builder turns a Zod schema plus a typed field-config map into a fully wired, accessible form. It lives at @/components/forms and is shared infrastructure — not a module. You describe what the form is (schema), how each field renders (config), and where the strings come from (i18n keys); the builder handles state, validation, layout, error resolution, and submission.

It replaces the older <ZodForm> + react-hook-form stack. Every <ZodForm> call site carried a cast — form as any or form as never — because the sub-section schema was narrower than the full form schema, and those casts hid whether the field names being passed actually existed. The new builder makes the field-name boundary type-safe: omitting a schema field or naming an unknown one is a compile error.

What it solves

The old flow had three structural problems the builder is designed around:

Tech stack

Public API surface

Everything is re-exported explicitly from @/components/forms (no wildcard barrel). The full surface:

The form object — FormApi<TSchema>

useFormBuilder returns a form bound to the schema's value type, so field names autocomplete and selector slices are typed. Its members:

The built-in field types

The 18 built-in field types are exactly the keys of the renderer registry. Each maps a type discriminator to its config shape in FieldTypeRegistry:

Custom field types beyond these are contributed by modules through the slot system — they become valid type values everywhere FormFields<T> is used via TypeScript declaration merging on FieldTypeRegistry.

Quick start

The smallest viable form uses the monolithic <FormBuilder> shortcut: every schema field renders in declaration order under a single submit button.

import { z } from "zod/v4";

const schema = z.object({
  name: z.string().min(1),
  email: z.email(),
  subscribe: z.boolean(),
});

import type { FormFields } from "@/components/forms";

const fields: FormFields<typeof schema> = {
  name: { type: "text", label: "Name", placeholder: "Ana Silva" },
  email: { type: "text", label: "Email", placeholder: "ana@example.com" },
  subscribe: { type: "checkbox", label: "Subscribe to updates" },
};

import { FormBuilder } from "@/components/forms";

function SignupForm() {
  return (
    <FormBuilder
      formId="signup"
      schema={schema}
      fields={fields}
      onSubmit={(values) => console.log(values)}
      submitLabel="Save"
    />
  );
}

For anything beyond a single flat column — multiple cards, tabs, a section layout, or per-render overrides — call useFormBuilder directly and compose the primitives:

import { useFormBuilder } from "@/components/forms";

function SignupForm() {
  const form = useFormBuilder({ formId: "signup", schema, fields, onSubmit });

  return (
    <form.Provider>
      <form.Section titleKey="signup.section.account">
        <form.Fields names={["name", "email"]} />
      </form.Section>
      <form.Fields names={["subscribe"]} />
      <form.ErrorSummary />
      <form.SubmitButton>signup.save</form.SubmitButton>
    </form.Provider>
  );
}

<FormBuilder> is not a separate code path — it calls the same hook and renders the same primitives, so every guarantee (validation, error map, mutation wiring, distributed rendering) holds for both.

Submission

Pass exactly one of mutation or onSubmit to useFormBuilder. With a mutation, the form calls mutation.mutateAsync(values); otherwise it calls your onSubmit(values).

const form = useFormBuilder({
  formId: "customer",
  schema,
  fields,
  mutation: useCreateCustomer(),
  resetOnSuccess: true,
  onSuccess: (values) => toast.success(`Saved ${values.name}`),
  onError: (err) => console.error(err),
});

A thrown submit error does not land in TanStack's form-level state.errors; the builder captures it and surfaces it via form.useFormState((s) => s.submitError). See Submission for the full lifecycle, SubmitButtonGroup, and onAfter.

Validation

Validation is the Zod schema. On change, blur, and submit, the whole schema is parsed and each issue is resolved to a localized string through a four-level i18n fallback convention (scoped-path-with-code → scoped-path → generic-code → Zod's localized default). Developers never write error strings in TypeScript.

Fields may also carry optional per-field validate (sync, runs on change) and validateAsync (runs on blur, receives an AbortSignal).

See Validation for the error-map convention and per-field validators.

Conditional fields

disabled, required, and visible each accept a static boolean or a FieldValuesPredicate — a function over the whole values object that re-evaluates on every change. visible is the only one that unmounts the field; disabled and required flip ARIA flags only. required is a UI hint (the * indicator + aria-required) — hard validation always stays in Zod.

See Conditionals.

Arrays

The array field type binds a z.array(z.object(...)) schema to a repeatable fieldset. Each row renders via an item config — a StaticFormFields map keyed by the element schema's field names.

See Arrays.

Custom field types

Built-ins are resolved first; a module extends the set by contributing a renderer to FORM_SLOTS.FIELD_TYPES from its module.ts, and declaration-merging FieldTypeRegistry so the new type value autocompletes in FormFields<T>. The contributed component receives { name, config, field } where field is TanStack's own AnyFieldApi. Built-ins win on a key collision.

slotContribution<FormFieldType>(FORM_SLOTS.FIELD_TYPES, {
  type: "licensePlate",
  component: LicensePlateField,
});

See Custom Field Types.

Escape hatch

When the standard chrome is not enough, form.useField(name) returns a headless FieldHandle<TValue> — value, setValue, resolved error / errors, meta flags, and spreadable inputProps. Errors are already resolved against the i18n map; the handle exposes them as plain strings. See Escape Hatch.

Feature map

Out of scope

The builder is deliberately bounded. It does not provide:

• A visual / drag-and-drop form designer — forms are authored in code.
• Backend-defined forms — the schema and config are TypeScript, not a server payload.
• Multi-step wizards — composition spans cards and tabs within one submission, not a stepped flow controller.
• An upload pipeline — the file field commits raw File objects to form state; the submission handler is responsible for uploading and replacing them with whatever the API expects.