Cross-field rules
Declare checks that span several fields, such as a password confirmation or “pick at least two”, as rules. A rule gives the same verdict in the browser and on the server.
On this page
Declaring a rule
export const signup = defineForm(
z.object({
password: z.string().min(8),
confirm: z.string(),
}),
[sameAs('confirm', 'password', 'The passwords do not match')],
Rules next to the schema
);
const signupFields = formFields(signup);
Pass the definition instead of the schema
const parsed = parseForm(signup, formData);Pass defineForm the schema and an array of rules. The definition then goes to formFields and parseForm in place of the schema.
Rules are plain data, so they are sent to the browser with the fields.
The field names in a rule are checked against the schema’s types. A name the schema does not have is a type error.
Available rules
defineForm(schema, [
sameAs('confirm', 'password', 'The passwords do not match'),
minChecked('topics', 2, 'Pick at least two'),
requiredWhen('reason', 'status', 'rejected', 'Give a reason'),
]);sameAs(field, other, message):fieldmust equalother. Use it to confirm a password.minChecked(field, min, message): at leastminof the checkboxes sharing the name must be checked.requiredWhen(field, when, equals, message):fieldis required only whenwhenisequals.
Review form demo
A review form where the reason is required only for “Reject”, and at least two aspects must be checked.
Try it
- Check two aspects and choose “Reject”. Leave the reason empty and press “Submit”: the reason field shows an error.
- Switch back to “Accept”. The error on the reason goes away.
- Leave only one aspect checked and submit. The error asks for at least two.
Browser and server
The browser checks the live form and the server checks the submission, with the same evaluator.
In the browser, a field that fails a rule gets its error through setCustomValidity. It behaves like a built-in check: :user-invalid matches, and the message comes through the field’s error like any other.
When one field fails several rules, the message of the rule declared first is shown.
Translated wording
src/lib/signup-form.tsimport { mismatch, pickAtLeast } from '../messages/signup';
export const signup = defineForm(schema, [
sameAs('confirm', 'password', mismatch),
minChecked('topics', 2, () => pickAtLeast(2)),
]);A rule’s message can be a function instead of a string. The wording the browser shows is fixed in the locale current when formFields runs.
It works the same way as zod’s own messages. Where to call formFields is covered in Errors.
Checks outside the rules
z.object({
start: z.iso.date(),
end: z.iso.date(),
}).refine((value) => value.start <= value.end, {
message: 'The end comes before the start',
});Write any check the three rules cannot express as a .refine(). A .refine() runs only on the server.
A .refine() on the whole schema is listed in dropped as a check the browser does not run. Without a path, its error is in form.formError.
Pitfall
A .refine() on a single field, a nested object or a row is not listed in dropped yet. The browser shows nothing, and the error appears only after the server checks the submission.