Errors
Errors from browser validation and from the server both show up in field().error. Learn where to show them and where focus goes when a submission fails.
On this page
Field errors
const title = form.field('title');
<label htmlFor="title">Title</label>
<input {...title.input} aria-describedby="title-error" id="title" />
{title.error !== undefined && <p id="title-error">{title.error}</p>}
Rendered only while `error` is seterror on the value field() returns holds the field’s message. invalid is whether there is one.
An error appears when the person leaves the field or submits. No new error appears while typing, and one already shown clears once the value is fixed.
A server error stays until the field is edited. An error from browser validation takes precedence over it.
Changing the wording
z.object({
title: z.string().min(1, 'Enter a title').max(120, 'Keep it to 120 characters'),
});What is shown is zod’s own message. To change it, write it in the schema.
The browser and the server both read the message from the same schema, so the wording is the same whichever side finds the error.
Translated wording
src/routes/[locale]/talks/new/page.tsximport { titleMissing } from '../../../../messages/talk';
const talkSchema = z.object({
title: z.string().min(1, { error: () => titleMissing() }),
});
export default function NewTalkPage() {
const talkFields = formFields(talkSchema);
return <TalkForm action={createTalk} fields={talkFields} />;
}Hand zod the message as a function, not as the string it returns. zod calls it when it reports the error, so the wording follows the locale at that moment. Writing a message such as titleMissing is covered in Messages.
defineForm rules take a function too, as in requiredWhen('reason', 'status', 'rejected', reasonRequired).
Pitfall
Call formFields during the render. Called at module scope, the messages stay in whatever locale was active when the module first loaded.
How the locale is set when a Server Action calls parseForm is covered in Current locale.
Focus on the failed field
When a submission fails, focus moves to the first failed field on the page. There is nothing to write for this.
“First” means document order, not the order of the schema’s keys.
Pitfall
A state you build by hand needs a fresh token. With the same token, two identical failures in a row read as the same result, and focus does not move.
Form-level errors
<form {...form.props} action={formAction}>
{form.formError.message !== undefined && (
<p {...form.formError.props}>{form.formError.message}</p>
Adds an `id` and `tabIndex={-1}`
)}
{/* fields */}
</form>An error that belongs to no field goes to form.formError. A .refine() on the whole schema with no path is one example.
Spread formError.props onto the element that shows it. The element can then take focus, so a screen reader announces the error.
Place it above the fields. When fields failed too, focus lands here first, and Tab moves on to the fields.
Failures found on the server
actions.tsexport async function createTalk(
_prev: FormState,
formData: FormData,
) {
const parsed = parseForm(talkSchema, formData);
if (!parsed.success) return parsed.state;
if (await titleExists(parsed.data.title)) {
return {
...parsed.state,
errors: { title: 'A talk with this title already exists' },
Add the message under the field’s name
};
}
await saveTalk(parsed.data);
redirect(href('/talks'));
}Some failures, such as a title that is already taken, can only be found by checking the database. When you find one after parseForm succeeds, add the error to parsed.state and return it.
parsed.state already holds the submitted values and a fresh token, so the values come back into the fields.
Error demo
A sign-up form with a handle and a password, with every message taken from the page’s schema.
Try it
- Type
abas the handle and leave the field. The error asks for at least 3 characters. - Make the confirmation different from the password. The error says they do not match.
- Leave a field empty and press “Sign up”. Focus moves to the first field that failed.