Validation and submission

ErlForm reads the schema to build the UI. Install validation separately in useForm. Try a short name or invalid email to display field errors, then correct them and submit.

Usage

Use your form instance from useForm. See the initial setup.

const schema = z.object({ name: z.string().min(2) });

const form = useForm({
  defaultValues: { name: "" },
  validators: { onChange: schema },
});

<ErlForm form={form} schema={schema} />

The demo parses submitted values explicitly. For form initialization and submission, follow the Quick Start.

Saving to an API

onSubmit: async ({ value }) => {
  const parsed = schema.safeParse(value);
  if (!parsed.success) return;
  const response = await fetch("/api/profile", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(parsed.data),
  });
  if (!response.ok) throw new Error("Saving failed");
}

Provide your own endpoint and show a useful error state on request failure. See server errors for field mapping; use isSubmitting to prevent duplicate requests.

Defaults and transforms

defaultValues must match the UI input shape: string, boolean, object, array, File, or Date. Schema .default() and .catch() do not automatically initialize state. Validation does not guarantee that onSubmit receives transformed output; call schema.parse/safeParse when you need it.

When input and output types differ, distinguish z.input and z.output. Pipeline inference reads the input side, and fieldConfig should describe the form's input state.

Errors and conditional fields

The first entry in meta.errors is displayed. Strings, Error objects, and objects with a message property are normalized into text. requiredIf controls UI state, not Zod rules. Hidden, disabled, and readonly fields remain in state and can still be validated. Define conditional schema rules accordingly.

An empty number becomes undefined. An optional string does not automatically convert an empty string to undefined.

Resetting and editing data

Use form.reset() to return to defaultValues, or form.reset(data) after loading editable data. Convert API data into the expected UI shape, especially Date values and arrays. Reset buttons should use type button.

Built-in controls do not generally forward handleBlur in 1.0.0. Use onChange/onSubmit validation or a custom input for blur/touched flows. Subscribe to canSubmit and isSubmitting with form.Subscribe when rendering pending or disabled submit controls.