Escape Hatch: useField

Every built-in field type renders through the registry: you give useFormBuilder a fields config, drop a form.Field name="…" (or form.Fields) into the tree, and the form supplies the chrome — label, input, validation messages, accessibility wiring. That covers the vast majority of forms.

When none of the 17 built-in renderers is the right shape — a custom card picker, an inline editor, a widget with its own internal layout — you reach for form.useField. It is the headless escape hatch: it hands you the field's value, setter, resolved errors, and meta flags, and lets you render whatever JSX you like, while the field stays fully wired into the form's validation and submission pipeline.

This page documents that hook and the DEV-only warning that fires when a schema field is never mounted in the rendered tree.

form.useField(name)

form.useField subscribes to one field by name and returns a FieldHandle. It must be called inside <form.Provider> — calling it outside throws, because it has no form store to bind to.

function PriorityPicker({form}: {form: FormApi<typeof schema>}): ReactElement {
    const field = form.useField("priority");

    return (
        <div role="radiogroup" aria-label="Priority">
            {(["low", "medium", "high"] as const).map((level) => (
                <button
                    type="button"
                    key={level}
                    aria-pressed={field.value === level}
                    onClick={() => field.setValue(level)}
                >
                    {level}
                </button>
            ))}
            {field.error ? (
                <p className="text-destructive text-sm">{field.error}</p>
            ) : null}
        </div>
    );
}

The hook is bound to the schema through useFormBuilder, so name autocompletes from the schema keys and field.value carries the precise type of that field.

The FieldHandle shape

This is the exact surface returned by form.useField. There are no handleChange / handleBlur methods on the handle — writes go through setValue, and native inputs get wired through inputProps.

type FieldHandle<TValue> = {
    value: TValue;
    setValue: (value: TValue) => void;
    error: string | undefined;
    errors: string[];
    meta: {
        isDirty: boolean;
        isTouched: boolean;
        isValidating: boolean;
    };
    inputProps: {
        name: string;
        value: TValue;
        onChange: (event: ChangeEvent<HTMLInputElement>) => void;
        onBlur: () => void;
    };
};

inputProps is for native text inputs only

inputProps is a convenience for the common case: a custom layout that still wraps a plain <input> or <textarea>. Its onChange reads event.target.value — a string — and writes that into the field. Spreading it onto a native text element gives you a controlled input with no boilerplate.

function InlineNameEditor(): ReactElement {
    const field = form.useField("name");

    return (
        <label className="flex flex-col gap-1">
            <span className="text-sm font-medium">Name</span>
            <input {...field.inputProps} className="rounded-md border px-2 py-1" />
            {field.error ? (
                <span className="text-destructive text-xs">{field.error}</span>
            ) : null}
        </label>
    );
}

useField vs. a custom slot type

Both let you render UI the registry doesn't ship. The discriminator is reuse, not complexity.

If you find yourself copying the same useField widget into a second form, that is the signal to promote it to a slot type. The slot path lives entirely in the contributing module — see the licensePlate worked example in the _development module — and never touches src/components/forms/.

DEV warning: schema fields never mounted

It is easy to add a key to the Zod schema (and therefore to FormFields<T>), then forget to render it anywhere — no form.Field, no form.Fields, no form.useField. The form still carries a default value for that field, so submissions silently include it (usually as undefined) and nothing in the UI complains.

The form builder catches this in development. Each form.Field and form.useField mount registers its name in a cumulative set. After a short window of render stability (one second), the builder diffs the schema's field keys against that set and logs any that were never mounted:

[form:my-form] Schema fields not mounted in the rendered tree: notes, language

The fix when you do see the warning is one of:

Putting it together

A custom control bound through useField, living inside the same form.Provider as the registry-rendered fields, submitting as one unit:

const schema = z.object({
    name: z.string().min(1),
    priority: z.enum(["low", "medium", "high"]),
});

const fields: FormFields<typeof schema> = {
    name: {type: "text", label: "Name"},
    priority: {type: "select", label: "Priority", options: [
        {label: "Low", value: "low"},
        {label: "Medium", value: "medium"},
        {label: "High", value: "high"},
    ]},
};

function TaskForm(): ReactElement {
    const form = useFormBuilder({
        formId: "task",
        schema,
        fields,
        defaultValues: {priority: "low"},
        onSubmit: (values) => save(values),
    });

    return (
        <form.Provider>
            <form.Field name="name" />
            <PriorityPicker form={form} />
            <form.SubmitButton>Save</form.SubmitButton>
        </form.Provider>
    );
}

Here name renders through the registry, priority renders through the custom PriorityPicker (which calls form.useField("priority")), and both are validated and collected on submit. Because priority is bound via useField, the DEV warning stays quiet — the field counts as mounted.