Forms in Next.js

A sign-up form that answers back

The tea shop has a club: one new tea every month. To join, a visitor types a name and an email and clicks Join. A Server Action saves the new member: a function that runs on the server when the form is sent. (Your first Next.js app built one that saves a note.) But people make mistakes. They type one letter for a name, or half an email. The server has to answer: what was wrong, and in which box. Then the visitor fixes it without typing everything again.

Here is that form. It's a real Next.js 16.4.3 project, built with next build and run with next start. Then real Chrome used it: it typed A and asha@, and clicked Join. The Steps tab opens on that click.

1"use server";2 3import { z } from "zod";4 5const member = z.object({6  name: z.string().trim().min(2, "Write at least 2 letters."),7  email: z.email("Write an email address, like asha@example.com."),8});9 10export type JoinState = {11  message: string;12  errors: { name?: string[]; email?: string[] };13  values: { name: string; email: string };14};15 16export async function join(previous: JoinState, formData: FormData): Promise<JoinState> {17  const values = {18    name: String(formData.get("name") ?? ""),19    email: String(formData.get("email") ?? ""),20  };21  const result = member.safeParse(values);22  if (!result.success) {23    const errors = z.flattenError(result.error).fieldErrors;24    return { message: "Check the fields above.", errors, values };25  }26  // A real shop would save the new member here.27  return { message: `Welcome to the club, ${result.data.name}!`, errors: {}, values: { name: "", email: "" } };28}

After step 4, each box has a message under it: Write at least 2 letters. under Name, and Write an email address, like asha@example.com. under Email. Under the button is Check the fields above. The boxes still hold A and asha@. The click made one request, a POST to /club, and no page load. Pick step 9: after the visitor fixed both boxes, the form said Welcome to the club, Asha!

The form has four files, and each one does one job:

• app/club/actions.ts, open above, is the Server Action. Lines 5 to 8 describe a good member with Zod, a library that checks values, and join returns what the form should show.
• app/club/join-form.tsx is the form. It hands join to useActionState, a React hook, and shows what join returned.
• app/club/join-button.tsx is the Join button. It knows when its form is being sent.
• app/club/page.tsx is the page at /club. It shows a heading and the form.

useActionState: the action's answer becomes the form's state

A Server Action given straight to a form, as in <form action={join}>, runs on the server, but the form never sees what it returns. To show the answer, the form needs somewhere to keep it. That's useActionState, from React. It wraps the action, and keeps what the action returned last as the form's state. (Form actions, in the React course, teaches the hook on its own. Here it's connected to a Server Action.)

1"use client";2 3import { useActionState } from "react";4import { join, type JoinState } from "./actions";5import JoinButton from "./join-button";6 7const empty: JoinState = { message: "", errors: {}, values: { name: "", email: "" } };8 9export default function JoinForm() {10  const [state, formAction] = useActionState(join, empty);11  return (12    <form action={formAction}>13      <label htmlFor="name">Name</label>14      <input id="name" name="name" defaultValue={state.values.name} aria-describedby="name-error" />15      <p id="name-error">{state.errors.name?.[0]}</p>16 17      <label htmlFor="email">Email</label>18      <input id="email" name="email" defaultValue={state.values.email} aria-describedby="email-error" />19      <p id="email-error">{state.errors.email?.[0]}</p>20 21      <JoinButton />22      <p aria-live="polite">{state.message}</p>23    </form>24  );25}26 

Line 1 makes the file a Client Component, because useActionState keeps state in the browser, so it needs a Client Component. Line 4 imports join from the actions file, and its type, JoinState. Line 7 is the state before anything was sent: no message, no errors, and empty values.

Line 10 is the hook. It takes two things and gives back three; this form uses the first two:

• It takes the action, join, and the first state, empty.
• It gives back state, which is empty at first and then whatever join returned last, and formAction, a new function that calls join for you.
• The third, isPending, says whether join is still running. The club form leaves it out, and its button finds out another way, with useFormStatus.

Line 12 gives formAction to the form. When the visitor clicks Join, React collects the boxes into a FormData object and calls formAction. That sends them to join on the server, and when join answers, React draws the form again with the answer as state. The rest of the form reads state: lines 15 and 19 show the errors, and line 22 the message.

Now the action. Giving it to useActionState changes what it receives:

1"use server";2 3import { z } from "zod";4 5const member = z.object({6  name: z.string().trim().min(2, "Write at least 2 letters."),7  email: z.email("Write an email address, like asha@example.com."),8});9 10export type JoinState = {11  message: string;12  errors: { name?: string[]; email?: string[] };13  values: { name: string; email: string };14};15 16export async function join(previous: JoinState, formData: FormData): Promise<JoinState> {17  const values = {18    name: String(formData.get("name") ?? ""),19    email: String(formData.get("email") ?? ""),20  };21  const result = member.safeParse(values);22  if (!result.success) {23    const errors = z.flattenError(result.error).fieldErrors;24    return { message: "Check the fields above.", errors, values };25  }26  // A real shop would save the new member here.27  return { message: `Welcome to the club, ${result.data.name}!`, errors: {}, values: { name: "", email: "" } };28}29 

Line 1, "use server", makes every function this file exports a Server Action. On line 16, join takes previous first: the state the form has now. The fields come second, as formData. A Server Action that a form calls directly gets only formData; once useActionState calls it, the state comes first. join doesn't need previous, but it must still take it, so that formData is the second one.

Lines 10 to 14 describe the state, and join returns one on both paths: line 24 when something is wrong, and line 27 when everything is right. What it returns travels to the browser, so return only what the form needs to show.

The page around the form stays a Server Component. Line 8 of app/club/page.tsx renders <JoinForm />; only the form and the button are Client Components. The build printed ○ /club: the page, form included, was made once during the build, and the form's state lives in the browser.

Checking the fields on the server with Zod

A form's fields arrive as text, from someone you don't know. Before you save them, check each one. You could write the checks by hand, with an if for each rule. A schema is shorter: a description of what good data looks like, which a library compares the data with. Zod is the library in the Next.js docs' example, and its latest version on October 30, 2026 was 4.6.7. The example adds it to package.json, as npm install zod does.

In the action, lines 5 to 8 are the schema:

• z.object(…) on line 5 says the data is an object with the keys listed inside.
• Line 6 says name is a string. .trim() removes spaces at both ends first, and .min(2, "Write at least 2 letters.") needs at least 2 characters. The text is the message the visitor sees when the rule fails.
• Line 7, z.email(…), needs a string shaped like an email address, with its own message.

Lines 17 to 20 read the two fields from formData. formData.get("name") gives the box named name, or null if there's none, and String(… ?? "") turns a missing box into an empty string. Line 21 asks Zod to check them with safeParse. It never throws: it returns an object whose success says whether the data passed. If it passed, result.data is the checked data, with the spaces trimmed, which line 27 uses for the name. If it failed, result.error lists every rule that failed.

Line 23 turns that list into one message list per field with z.flattenError, and keeps its fieldErrors. For A and asha@, Zod failed both rules, and the recording shows what came back:

{
  "name": ["Write at least 2 letters."],
  "email": ["Write an email address, like asha@example.com."]
}

Each field gets a list, because one value can break several rules. A field with no problem isn't in the object at all.

Why on the server

Browsers can check a form too. required on an input stops an empty box, and type="email" stops text without @, before anything is sent. Those checks are worth adding: the visitor gets an answer at once. But they only run in the browser, on your page.

A Server Action is a POST request to your server, and anyone can send one, with any fields, without your page. Only a check inside the action runs for every request. So the action is where the rules have to be; the browser's checks are a faster first answer on top. (Forms and inputs covers the browser's own checks.)

Showing each error next to its field

state.errors has a list for each field that failed. The form shows the first message of each list right under its box. Look at lines 13 to 15 of app/club/join-form.tsx again:

• Line 13, <label htmlFor="name">, names the box. A click on the label puts the cursor in the box, and a screen reader reads Name when the box gets focus.
• Line 15 shows state.errors.name?.[0], the first message for name. ?. stops at undefined when there's no list, so the paragraph is empty then.
• On line 14, aria-describedby="name-error" points the box at that paragraph, by its id. A screen reader then reads the message with the box's name.

Lines 17 to 19 do the same for Email. The message on line 22 has aria-live="polite": a screen reader reads it out when it changes, after what it's reading now. (Accessible React explains both attributes.)

Each row is one form the recorder sent, what join returned, and what the form then showed. The first is the click in the Steps tab; the other two are in the Network tab, sent without JavaScript.

Only the field that broke a rule gets a message. That's what makes field errors useful: the visitor looks at one box, not the whole form.

Keeping what the visitor typed

Why does join return values too? Because of what React does after an action. When a form's action finishes without throwing, React resets the form: it calls the browser's form.reset(), which puts every box back to its default value. Returning errors still counts as finishing. React doesn't look at what the action returned. The reset only changes boxes React doesn't control: a box whose value comes from state keeps it. The club's boxes have no value, so without help, a mistake empties the whole form.

The help is defaultValue. React updates each box's default first, and resets the form after. So if the default is what the visitor typed, the reset puts it back. That's what defaultValue={state.values.name} on line 14 does, with the values join returned on line 24. (Form actions shows the rule in React's own code.) Compare the two versions:

1"use client";2 3import { useActionState } from "react";4import { join, type JoinState } from "./actions";5import JoinButton from "./join-button";6 7const empty: JoinState = { message: "", errors: {}, values: { name: "", email: "" } };8 9export default function JoinForm() {10  const [state, formAction] = useActionState(join, empty);11  return (12    <form action={formAction}>13      <label htmlFor="name">Name</label>14      <input id="name" name="name" aria-describedby="name-error" />15      <p id="name-error">{state.errors.name?.[0]}</p>16 17      <label htmlFor="email">Email</label>18      <input id="email" name="email" aria-describedby="email-error" />19      <p id="email-error">{state.errors.email?.[0]}</p>20 21      <JoinButton />22      <p aria-live="polite">{state.message}</p>23    </form>24  );25}

Without defaultValue, the messages arrive and the boxes are empty: the visitor has to type asha@ again to fix one letter. With it, the boxes hold A and asha@. After a success, line 27 returns empty values, so the reset empties the form, ready for the next person.

Before the JavaScript has loaded

A visitor on a slow phone may click Join before the page's JavaScript has arrived. Then React isn't running yet, and the browser sends the form the plain way: a POST that loads a new page. The form still works, because React wrote it so the browser can send it on its own. This is called progressive enhancement: the page works with HTML alone, and gets better once the JavaScript runs.

The recorder sent the form that way too, without any JavaScript. Open the Network tab and pick /club first:

1"use server";2 3import { z } from "zod";4 5const member = z.object({6  name: z.string().trim().min(2, "Write at least 2 letters."),7  email: z.email("Write an email address, like asha@example.com."),8});9 10export type JoinState = {11  message: string;12  errors: { name?: string[]; email?: string[] };13  values: { name: string; email: string };14};15 16export async function join(previous: JoinState, formData: FormData): Promise<JoinState> {17  const values = {18    name: String(formData.get("name") ?? ""),19    email: String(formData.get("email") ?? ""),20  };21  const result = member.safeParse(values);22  if (!result.success) {23    const errors = z.flattenError(result.error).fieldErrors;24    return { message: "Check the fields above.", errors, values };25  }26  // A real shop would save the new member here.27  return { message: `Welcome to the club, ${result.data.name}!`, errors: {}, values: { name: "", email: "" } };28}

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="preload" as="script" fetchpriority="low" href="/_next/static/chunks/3cfn99dbrcvvp.js">
    <script src="/_next/static/chunks/2gsxhio73malr.js" async=""></script>
    <script src="/_next/static/chunks/2ki52vdnbo2ft.js" async=""></script>
    <script src="/_next/static/chunks/0ooaq-girjaeh.js" async=""></script>
    <script src="/_next/static/chunks/turbopack-3-ry682tkyiqk.js" async=""></script>
    <script src="/_next/static/chunks/1tq6ppe__m8m-.js" async=""></script>
    <script src="/_next/static/chunks/0am_g01o68zh_.js" async=""></script>
    <title>Tea shop</title>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
  </head>
  <body>
    <div hidden="">
      <!--$-->
      <!--/$-->
    </div>
    <!--&-->
    <!--&-->
    <main>
      <h1>Join the tea club</h1>
      <p>One new tea every month, with a letter about where it grows.</p>
      <form action="" enctype="multipart/form-data" method="POST">
        <input type="hidden" name="$ACTION_REF_1">
        <input type="hidden" name="$ACTION_1:0" value="{&quot;id&quot;:&quot;60edffa33aadbf415a8db4874924460d609967200a&quot;,&quot;bound&quot;:&quot;$@1&quot;}">
        <input type="hidden" name="$ACTION_1:1" value="[{&quot;message&quot;:&quot;&quot;,&quot;errors&quot;:{},&quot;values&quot;:{&quot;name&quot;:&quot;&quot;,&quot;email&quot;:&quot;&quot;}}]">
        <input type="hidden" name="$ACTION_KEY" value="kfb299cc11de108bcb378e0210cf0e99a">
        <label for="name">Name</label>
        <input id="name" aria-describedby="name-error" name="name" value="">
        <p id="name-error"></p>
        <label for="email">Email</label>
        <input id="email" aria-describedby="email-error" name="email" value="">
        <p id="email-error"></p>
        <button>Join</button>
        <p aria-live="polite"></p>
      </form>
    </main>
    <!--$-->
    <!--/$-->
    <!--/&-->
    <!--/&-->
    <script id="_R_">…</script>
    <script src="/_next/static/chunks/3cfn99dbrcvvp.js" async=""></script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
  </body>
</html>

In the HTML of /club, the form is <form action="" enctype="multipart/form-data" method="POST">: it posts to the page it's on. Inside it, before the boxes, are hidden fields that React wrote, which the browser sends along with the boxes. They name the action, and carry the form's current state. So the state the action returns ends up in the HTML too: one more reason to return only what the form shows.

Now pick POST /club, without JavaScript: A and asha@. The answer is 200, and a whole new HTML page. Next.js ran join, then rendered the page with the state it returned. The boxes are value="A" and value="asha@", both messages are there, and so is Check the fields above. The same defaultValue did it: on the server, a default value is the value in the HTML. Pick without JavaScript: Asha: the welcome message, and empty boxes.

With JavaScript running, the trip is different, and the Steps tab above showed it: one fetch, a POST to /club with a next-action header that names the action, answered 200 with text/x-component. That answer is an RSC payload: data that React reads, holding what the action returned. React put it in state and drew the form again, with no new page. A redirect from an action works in a similar way; Redirects shows a 303 without JavaScript and a client-side move with it.

A Join button that knows the form is busy

On a slow network, a visitor clicks Join and nothing seems to happen. They click again, and send the form twice. The button should say that the form is on its way, and refuse a second click. For that, it needs to know whether its form is being sent. useFormStatus, from react-dom, tells it:

1"use client";2 3import { useFormStatus } from "react-dom";4 5export default function JoinButton() {6  const { pending } = useFormStatus();7  return <button disabled={pending}>{pending ? "Joining…" : "Join"}</button>;8}9 

Line 3 imports the hook from react-dom, not react. Line 6 reads pending: true from the click until the action has answered. Line 7 turns the button off with disabled while it's true, and changes its text to Joining….

useFormStatus reports on the form around the component that calls it. So the button has to be its own component, rendered inside the <form>, as line 21 of join-form.tsx does. Called in the component that renders the form, it has no form around it. Both versions below were recorded on a slow network: Chrome held every request back before sending it, the way a weak phone signal does. Pick each one and look at step 8, the click on Join:

1"use client";2 3import { useActionState } from "react";4import { useFormStatus } from "react-dom";5import { join, type JoinState } from "./actions";6 7const empty: JoinState = { message: "", errors: {}, values: { name: "", email: "" } };8 9export default function JoinForm() {10  const [state, formAction] = useActionState(join, empty);11  const { pending } = useFormStatus();12  return (13    <form action={formAction}>14      <label htmlFor="name">Name</label>15      <input id="name" name="name" defaultValue={state.values.name} aria-describedby="name-error" />16      <p id="name-error">{state.errors.name?.[0]}</p>17 18      <label htmlFor="email">Email</label>19      <input id="email" name="email" defaultValue={state.values.email} aria-describedby="email-error" />20      <p id="email-error">{state.errors.email?.[0]}</p>21 22      <button disabled={pending}>{pending ? "Joining…" : "Join"}</button>23      <p aria-live="polite">{state.message}</p>24    </form>25  );26}

Called in JoinForm, which renders the form, pending stayed false: while the request was on its way, the button said Join. In JoinButton, it said Joining…, and Chrome showed it turned off. Step 9, in both, is the welcome message once the answer arrived.

useFormStatus also gives data (the FormData being sent), method and action, so a button could say Joining as Asha…. It works for any form, whatever its action. A form that already calls useActionState has a third way: the hook's third value, isPending. Pending and optimistic UI compares the ways to know an action is running.

Search forms with next/form

Not every form changes data. A search box only asks for a list. Its answer belongs in the address, like /teas?q=green, so the visitor can share it, bookmark it, or go Back to it. The part after ? is the address's search params, which a page reads with its searchParams prop (Search params teaches it).

HTML already has such a form: with no method, a <form action="/teas"> sends a GET request, and puts every named field into the address. But the browser loads a whole new page for it. Next.js has its own form for this, Form, from next/form. Give it a string action, and it does three more things:

• Client-side navigation. On submit, Next.js's router moves to the new address without a page load, as a Link does (Linking and navigating).
• Prefetching. When the form comes on the screen, the router already fetches the target page's static shell: its layouts and its loading UI.
• Progressive enhancement. Its HTML is a plain <form action="/teas">, so before the JavaScript has loaded, the browser sends it the ordinary way.

1import Form from "next/form";2 3export default function Home() {4  return (5    <main>6      <h1>Tea shop</h1>7      <Form action="/teas">8        <label htmlFor="q">Search teas</label> <input id="q" name="q" />{" "}9        <label htmlFor="sort">Sort by</label>{" "}10        <select id="sort" name="sort" defaultValue="name">11          <option value="name">Name</option>12          <option value="price">Price</option>13        </select>{" "}14        <button>Search</button>15      </Form>16    </main>17  );18}19 

Line 1 imports Form. Line 7 opens it with action="/teas", the page to go to. The page stays a Server Component: Form brings its own browser code. Line 8 is the box named q, and line 10 a menu named sort, which starts on name. Every named field becomes a search param, so the menu is a filter with no extra code. app/teas/page.tsx reads them with await searchParams, in a part wrapped in Suspense with Loading teas… as its fallback. Now compare it with a plain <form>:

1export default function Home() {2  return (3    <main>4      <h1>Tea shop</h1>5      <form action="/teas">6        <label htmlFor="q">Search teas</label> <input id="q" name="q" />{" "}7        <label htmlFor="sort">Sort by</label>{" "}8        <select id="sort" name="sort" defaultValue="name">9          <option value="name">Name</option>10          <option value="price">Price</option>11        </select>{" "}12        <button>Search</button>13      </form>14    </main>15  );16}

Both ended at the same address, /teas?q=green&sort=name, with the same two teas. The trips there differ. The plain form made a document request: a whole new page. The next/form version made no page load. Opening / had already fetched two parts of /teas, with the next-router-prefetch header, because the form was on the screen. Search then made one fetch with the rsc header, for the rest of the page. On the slow network, the address changed right after the click, and Search results and Loading teas… showed while that request was on its way: they came from the shell fetched before.

Each row compares the two forms, as recorded:

Form also takes replace (change the current history entry instead of adding one), scroll and prefetch, like Link. It doesn't take method, encType or target, because they would turn its own behavior off; use a plain <form> for those. Given a function instead of a string, Form acts like React's <form> and calls it as a Server Action, without prefetching, since the action decides where to go.

Which tool does each form need?

A shop has two kinds of forms. One kind changes data and answers on the same page. The other finds data, and its answer is another address. Each row asks one question of both:

A form that changes data often uses three tools at once: Zod in the action, useActionState in the form, and useFormStatus in its button. Sort each job into the tool that does it:

Common mix-ups

• "The browser's checks are enough." No. required and type="email" only run on your page. A Server Action is a POST anyone can send, so it checks every field itself.
• "React only resets the form when the action succeeds." No. It resets after any action that finishes without throwing, even one that returns errors. Give each box its defaultValue from the state.
• "Errors should be thrown." No. A wrong field is an expected problem: return it in the state, and the form shows it. A thrown error goes to error.tsx instead (Error handling).
• "useFormStatus works anywhere in the form's component." No. It reads the form around the component that calls it. Call it in a component rendered inside the form.
• "A form with useActionState needs JavaScript." No. With a Server Action, the browser can send it before the JavaScript loads, and Next.js answers with the page rendered from the new state.
• "next/form is for every form." No. Its extras (prefetching, the client-side navigation) are for a string action: a search or filter. For a form that changes data, a Server Action does the work.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page.

"use server";

import { z } from "zod";

const member = z.object({
  name: z.string().trim().min(2, "Write at least 2 letters."),
  email: z.email("Write an email address, like asha@example.com."),
});

export type JoinState = {
  message: string;
  errors: { name?: string[]; email?: string[] };
  values: { name: string; email: string };
};

export async function join(previous: JoinState, formData: FormData): Promise<JoinState> {
  const values = {
    name: String(formData.get("name") ?? ""),
    email: String(formData.get("email") ?? ""),
  };
  const result = member.safeParse(values);
  if (!result.success) {
    const errors = z.flattenError(result.error).fieldErrors;
    return { message: "Check the fields above.", errors, values };
  }
  // A real shop would save the new member here.
  return { message: `Welcome to the club, ${result.data.name}!`, errors: {}, values: { name: "", email: "" } };
}

import Form from "next/form";

export default function Home() {
  return (
    <main>
      <h1>Tea shop</h1>
      <Form action="/teas">
        <label htmlFor="q">Search teas</label> <input id="q" name="q" />{" "}
        <label htmlFor="sort">Sort by</label>{" "}
        <select id="sort" name="sort" defaultValue="name">
          <option value="name">Name</option>
          <option value="price">Price</option>
        </select>{" "}
        <button>Search</button>
      </Form>
    </main>
  );
}

"use client";

import { useActionState } from "react";
import { useFormStatus } from "react-dom";
import { join, type JoinState } from "./actions";

const empty: JoinState = { message: "", errors: {}, values: { name: "", email: "" } };

export default function JoinForm() {
  const [state, formAction] = useActionState(join, empty);
  const { pending } = useFormStatus();
  return (
    <form action={formAction}>
      <label htmlFor="name">Name</label>
      <input id="name" name="name" defaultValue={state.values.name} aria-describedby="name-error" />
      <p id="name-error">{state.errors.name?.[0]}</p>

      <label htmlFor="email">Email</label>
      <input id="email" name="email" defaultValue={state.values.email} aria-describedby="email-error" />
      <p id="email-error">{state.errors.email?.[0]}</p>

      <button disabled={pending}>{pending ? "Joining…" : "Join"}</button>
      <p aria-live="polite">{state.message}</p>
    </form>
  );
}

"use client";

import { useFormStatus } from "react-dom";

export default function JoinButton() {
  const { pending } = useFormStatus();
  return <button disabled={pending}>{pending ? "Joining…" : "Join"}</button>;
}

"use client";

import { useActionState } from "react";
import { join, type JoinState } from "./actions";
import JoinButton from "./join-button";

const empty: JoinState = { message: "", errors: {}, values: { name: "", email: "" } };

export default function JoinForm() {
  const [state, formAction] = useActionState(join, empty);
  return (
    <form action={formAction}>
      <label htmlFor="name">Name</label>
      <input id="name" name="name" aria-describedby="name-error" />
      <p id="name-error">{state.errors.name?.[0]}</p>

      <label htmlFor="email">Email</label>
      <input id="email" name="email" aria-describedby="email-error" />
      <p id="email-error">{state.errors.email?.[0]}</p>

      <JoinButton />
      <p aria-live="polite">{state.message}</p>
    </form>
  );
}

"use client";

import { useActionState } from "react";
import { join, type JoinState } from "./actions";
import JoinButton from "./join-button";

const empty: JoinState = { message: "", errors: {}, values: { name: "", email: "" } };

export default function JoinForm() {
  const [state, formAction] = useActionState(join, empty);
  return (
    <form action={formAction}>
      <label htmlFor="name">Name</label>
      <input id="name" name="name" defaultValue={state.values.name} aria-describedby="name-error" />
      <p id="name-error">{state.errors.name?.[0]}</p>

      <label htmlFor="email">Email</label>
      <input id="email" name="email" defaultValue={state.values.email} aria-describedby="email-error" />
      <p id="email-error">{state.errors.email?.[0]}</p>

      <JoinButton />
      <p aria-live="polite">{state.message}</p>
    </form>
  );
}

"use server";

import { z } from "zod";

const member = z.object({
  name: z.string().trim().min(2, "Write at least 2 letters."),
  email: z.email("Write an email address, like asha@example.com."),
});

export type JoinState = {
  message: string;
  errors: { name?: string[]; email?: string[] };
  values: { name: string; email: string };
};

export async function join(previous: JoinState, formData: FormData): Promise<JoinState> {
  const values = {
    name: String(formData.get("name") ?? ""),
    email: String(formData.get("email") ?? ""),
  };
  const result = member.safeParse(values);
  if (!result.success) {
    const errors = z.flattenError(result.error).fieldErrors;
    return { message: "Check the fields above.", errors, values };
  }
  // A real shop would save the new member here.
  return { message: `Welcome to the club, ${result.data.name}!`, errors: {}, values: { name: "", email: "" } };
}

"use server";

import { z } from "zod";

const member = z.object({
  name: z.string().trim().min(2, "Write at least 2 letters."),
  email: z.email("Write an email address, like asha@example.com."),
  cups: z.coerce.number().int().min(1, "Choose from 1 to 10 cups.").max(10, "Choose from 1 to 10 cups."),
});

export type JoinState = {
  message: string;
  errors: { name?: string[]; email?: string[]; cups?: string[] };
  values: { name: string; email: string; cups: string };
};

export async function join(previous: JoinState, formData: FormData): Promise<JoinState> {
  const values = {
    name: String(formData.get("name") ?? ""),
    email: String(formData.get("email") ?? ""),
    cups: String(formData.get("cups") ?? ""),
  };
  const result = member.safeParse(values);
  if (!result.success) {
    const errors = z.flattenError(result.error).fieldErrors;
    return { message: "Check the fields above.", errors, values };
  }
  // A real shop would save the new member here.
  return { message: `Welcome to the club, ${result.data.name}!`, errors: {}, values: { name: "", email: "", cups: "" } };
}

export default function Home() {
  return (
    <main>
      <h1>Tea shop</h1>
      <form action="/teas">
        <label htmlFor="q">Search teas</label> <input id="q" name="q" />{" "}
        <label htmlFor="sort">Sort by</label>{" "}
        <select id="sort" name="sort" defaultValue="name">
          <option value="name">Name</option>
          <option value="price">Price</option>
        </select>{" "}
        <button>Search</button>
      </form>
    </main>
  );
}

import Form from "next/form";

export default function Home() {
  return (
    <main>
      <h1>Tea shop</h1>
      <Form action="/teas">
        <label htmlFor="q">Search teas</label> <input id="q" name="q" />{" "}
        <label htmlFor="sort">Sort by</label>{" "}
        <select id="sort" name="sort" defaultValue="name">
          <option value="name">Name</option>
          <option value="price">Price</option>
        </select>{" "}
        <button>Search</button>
      </Form>
    </main>
  );
}

Check your understanding

For each question, think about where the code runs, and what travels between the browser and the server.

Key takeaways

• useActionState(action, firstState), in a Client Component, gives back state, formAction and isPending. The form calls formAction, and what the Server Action returns becomes state.
• Called through useActionState, a Server Action gets the previous state first and the FormData second.
• Check every field inside the action, with a schema like Zod's and safeParse. Return z.flattenError(error).fieldErrors and show each field's first message under its box.
• React resets a form after any action that finishes without throwing. Return the typed values, and use them as each box's defaultValue; it works without JavaScript too, where Next.js renders the page from the new state.
• useFormStatus reports on the form around the component that calls it, so put it in a button rendered inside the form.
• For search and filters, Form from next/form puts the fields in the address, prefetches the target's shell, and moves there without a page load.

Coming next: Pending and optimistic UI. It shows progress while an action runs, and the result before the server answers, rolling back if it fails.