@k8ordo/form

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

text
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 field

Only 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

ts
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 required and parseForm reach 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 in dropped. parseForm runs every check on the server, those included.
  • formFields and parseForm throw as soon as they receive a schema the package cannot express.

Not guaranteed

  • Checks listed in dropped never 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 in dropped.
  • The range message from @k8ordo/ui’s NumberField is not zod’s wording.
  • A chosen file does not come back into its control after a failed submission.
k8ordo

React libraries that use Baseline features without holding back.