How it works
When and where @k8ordo/form checks the input, and what it does and does not guarantee.
On this page
Where the schema runs
server formFields(schema) → { fields, arrays, rules, dropped }
↓ props (JSON)
client useForm(fields, state) → props for <form>, input for each field
↓ submit
server parseForm(schema, data) → typed data, or errors per fieldOnly formFields and parseForm read the schema, and both run on the server. Of the schema, the browser receives only the JSON formFields returns.
As long as only server code imports the schema, zod never enters the browser bundle. Writing it with zod or zod/mini then makes no difference to the bundle.
The messages the browser shows are fixed when formFields runs, and travel in its JSON. How to call it so they follow the request’s language is in Errors.
Values and state
Typed values are read from the controls and never copied into React state. State holds only these five things the DOM cannot express.
- The message to show for a control that failed a check
- Server errors the user has not fixed yet
- The key that identifies each repeated row
- One dirty flag, read back from the DOM
- The row counts at render, used to detect added or removed rows
Since values are not kept in state, typing never re-renders. The browser’s reset and React’s reset after an action both work as they are.
Without JavaScript
Constraints such as required and minLength are attributes in the server-rendered HTML. Without JavaScript, or before it loads, the browser checks the input itself.
Once JavaScript loads, useForm sets noValidate on the form and runs the same checks in zod’s wording. noValidate is set on mount and never written into the HTML.
After a failed submission, the submitted values are rendered again as each control’s defaultValue. Nothing typed is lost, even without JavaScript.
Where the messages come from
For each kind of check, formFields hands the schema a value that fails only that check. The message that comes back is stored as the one the browser shows.
So a message of your own, such as min(1, '…'), reads the same in the browser and on the server.
How required is decided
z.object({ bio: z.string() });
// bio: { name: 'bio', type: 'text' }
z.object({ title: z.string().min(1) });
// title: { name: 'title', required: true, type: 'text', minLength: 1 }
z.object({ age: z.coerce.number().optional() });
// age: { name: 'age', type: 'number', step: 'any' }JSON Schema’s required means “the key is present”, which says nothing about an empty control. So formFields emits required only when the schema rejects what the control submits when left empty.
Above, the marked bio and age get no required, since bio accepts an empty string and age may be left empty. parseForm hands the schema the same values, so the browser and the server agree.
What each control submits when left empty is listed in Schema mapping.
Checks the browser skips
A .refine() on the whole schema or a regex with flags cannot be expressed as an HTML attribute. formFields lists such checks in dropped. Which checks it lists is in Schema mapping.
Outside production the list is also printed once per schema with console.warn. All of these checks still run on the server.
Rules declared with defineForm are not in dropped: the browser and the server check them with the same code. How to declare one is in Cross-field rules.
Rejected schemas
Apart from files, every submitted value is a string, so no input could satisfy z.number() or z.date(). Shapes such as z.record or a tuple have no name to submit under.
formFields and parseForm throw as soon as they receive such a schema, rather than build a form that could never pass or would misread the input.
The full list of rejected schemas is in Schema mapping.
Guarantees
useForm, which runs in the browser, imports neither zod nor the schema.- Typing does not re-render the form on every keystroke.
- Without JavaScript, the browser still stops a submission that breaks a constraint attribute.
- After a failed submission, the submitted values come back into the controls. A field marked
input: "password"is never echoed. - The browser shows the same message the server returns for the same check.
- For an empty control, the browser’s
requiredandparseFormreach the same verdict. - A check no HTML attribute can express, such as a
.refine()on the whole schema or a regex with flags, is listed indropped.parseFormruns every check on the server, those included. formFieldsandparseFormthrow as soon as they receive a schema the package cannot express.
Not guaranteed
- Checks listed in
droppednever run in the browser. - Until JavaScript loads, rules are not checked, and the messages are the browser’s own.
- A
.refine()on a single field, a nested object or a row is not listed indropped. - The range message from
@k8ordo/ui’sNumberFieldis not zod’s wording. - A chosen file does not come back into its control after a failed submission.