Field-Level Validation Errors with useActionState
Return structured validation results from actions and render inline per-field error messages.
Why Field-Level Errors?
When a form fails validation, users need to know exactly which field is wrong and why. A single banner saying "Something went wrong" forces them to guess.
In Next.js 15, Server Actions paired with useActionState let you return a structured result from the server and render an inline error right beneath each input.
emailis invalid → show the error under the email fieldpasswordis too short → show it under the password field
This lesson shows how to return that structure and render it cleanly.
Shaping the Action State
Start by deciding the shape of what your action returns. A good pattern keeps per-field errors in an errors map keyed by field name, where each value is an array of messages.
Defining a TypeScript type makes the contract explicit for both the action and the component.
export type FieldErrors = {
email?: string[];
password?: string[];
};
export type SignupState = {
errors?: FieldErrors;
// value the user typed, so we can re-fill the form
values?: { email?: string };
// a top-level message for non-field errors
message?: string;
};
export const initialState: SignupState = {};All lessons in this course
- Progressive Enhancement with the form Action Prop
- Pending and Loading States with useFormStatus
- Field-Level Validation Errors with useActionState
- Instant Feedback Using useOptimistic