Form, Field & useFormState

Form

Form is a <form> wrapper that handles validation and submission. It provides context for all <Field> components and the useFormState hook nested inside it.

With an adapter

When an adapter is configured, every schema key becomes an auto-rendered field. An empty <Form> with just a submit button is all you need:

const { Form, useFormState } = createForm({
  schema,
  adapter: shadcnAdapter,
  action,
  defaultValues: { username: "", email: "" },
});

const SignupForm = () => {
  const { isSubmitting } = useFormState();
  return (
    <Form className="space-y-4">
      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? "Signing up..." : "Sign up"}
      </button>
    </Form>
  );
};

Without an adapter

Without an adapter, <Form> requires explicit <Field render={...}> children for every field — there is nothing to auto-render. TypeScript enforces this: omitting render is a compile error.

const { Form, Field } = createForm({ schema, action }); // no adapter

<Form>
  <Field
    name="username"
    render={({ field }) => (
      <input value={field.value as string} onChange={field.onChange} />
    )}
  />
  <button type="submit">Submit</button>
</Form>

Field

Field renders a single form field. When placed inside a <Form>, it overrides the auto-generated version for that schema key. The name prop is typed against your schema — TypeScript will catch typos or missing keys at compile time.

The render prop

The render function receives a field object with everything you need to wire any input:

<Field
  name="bio"
  label="About you"
  render={({ field }) => (
    <textarea
      value={field.value as string}
      onChange={field.onChange}
      disabled={field.disabled}
      rows={4}
    />
  )}
/>

Overriding one field

Place a <Field> inside the form when you want to override only one or two fields while leaving the rest auto-rendered by the adapter:

<Form className="space-y-4">
  {/* This field is customised — the rest auto-render normally */}
  <Field
    name="avatar"
    label="Profile photo"
    render={({ field }) => <AvatarUpload onChange={field.onChange} />}
  />
  <button type="submit">Save</button>
</Form>

useFormState

useFormState is a hook that exposes live submission state. It reads from the same context that <Form> provides — it must be called inside a component that is rendered within that <Form> tree.

const { Form, useFormState } = createForm({ schema, adapter, action });

const SignupForm = () => {
  const { isSubmitting, result, submitCount } = useFormState();

  return (
    <Form className="space-y-4">
      {result?.status === "success" && (
        <p className="text-green-500">Account created!</p>
      )}
      {result?.status === "error" && result.message && (
        <p className="text-red-500">{result.message}</p>
      )}

      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? "Signing up..." : "Sign up"}
      </button>

      {submitCount > 2 && result?.status !== "success" && (
        <p className="text-sm text-muted-foreground">
          Having trouble? Check your input or try a different username.
        </p>
      )}
    </Form>
  );
};

useFormState can be called in any component rendered inside <Form> — it does not have to be in the same component that renders the form itself. This makes it easy to extract a submit button or a result banner into a separate component.

Override precedence

When multiple sources configure the same field, they merge from lowest to highest priority:

createForm({
  schema,
  adapter: shadcnAdapter,
  action,
  fields: {
    username: { label: "Handle" }, // priority 2 — overrides auto "Username"
  },
});

<Form>
  {/* priority 3 — wins over everything */}
  <Field name="username" label="Your unique handle" />
  <button type="submit">Submit</button>
</Form>

Error display

Field errors come from two sources: schema validation on submit, and fieldErrors returned by your action. Both map to the same per-field error state — your UI does not need to distinguish between them.

By default the adapter renders errors in its own style. You can replace the error display globally or per-field:

const MyError = ({ errorMessage }: { errorMessage: string }) => (
  <p className="mt-1 text-xs text-red-500">{errorMessage}</p>
);

createForm({
  schema,
  adapter: shadcnAdapter,
  action,
  GlobalErrorElement: MyError,       // default for all fields
  fields: {
    email: { ErrorElement: MyError }, // overrides GlobalErrorElement for email only
  },
});

Priority: Field prop ErrorElement > field config ErrorElement > GlobalErrorElement> adapter default.