Server Action Form

ProNew

A form for React 19 server actions: useActionState wiring, per-field errors and values kept after a failed submit, a pending submit button and a live status message.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/server-action-form

Usage

app/subscribe/actions.ts

app/subscribe/page.tsx

Exports

Export	Description
`ServerActionForm`	`<form action>` + `useActionState`. Provides the state to its fields.
`ServerField`	Labelled input (or `as={Textarea}`) with errors from `state.fieldErrors` and the value from `state.values`.
`ServerSubmit`	Submit button that is disabled and shows a spinner while the action runs.
`ServerFormStatus`	Live region for `state.message`.
`validateFormData(schema, formData)`	Parse a FormData with a zod-style schema and build the error state.
`formDataToValues`, `useServerForm`, `initialActionState`	Helpers.

Props

Prop (`ServerActionForm`)	Type	Description
`action`	`(prev, formData) => Promise<ActionState>`	The server action.
`initialState`	`ActionState`	Defaults to `{ status: "idle" }`.

On success the form resets (React clears an uncontrolled form after an action); return values with an error to refill the inputs.

ActionState: { status: "idle" | "success" | "error"; message?; fieldErrors?: Record<string, string[]>; values?: Record<string, string> }.

Accessibility

Each field links its label, hint and error with htmlFor and aria-describedby; an invalid field has aria-invalid="true".
The status region uses role="alert" for errors and role="status" for everything else, so a result is announced without moving focus.
The form sets aria-busy while the action runs and the submit button is disabled, which prevents a double submit.
Because the form uses a real action, it works before hydration when your action is a server action.

Testing

The component ships with a Testing Library test (server-action-form.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/server-action-form

Usage

app/subscribe/actions.ts

app/subscribe/page.tsx

Exports

Export	Description
`ServerActionForm`	`<form action>` + `useActionState`. Provides the state to its fields.
`ServerField`	Labelled input (or `as={Textarea}`) with errors from `state.fieldErrors` and the value from `state.values`.
`ServerSubmit`	Submit button that is disabled and shows a spinner while the action runs.
`ServerFormStatus`	Live region for `state.message`.
`validateFormData(schema, formData)`	Parse a FormData with a zod-style schema and build the error state.
`formDataToValues`, `useServerForm`, `initialActionState`	Helpers.

Props

Prop (`ServerActionForm`)	Type	Description
`action`	`(prev, formData) => Promise<ActionState>`	The server action.
`initialState`	`ActionState`	Defaults to `{ status: "idle" }`.

On success the form resets (React clears an uncontrolled form after an action); return values with an error to refill the inputs.

ActionState: { status: "idle" | "success" | "error"; message?; fieldErrors?: Record<string, string[]>; values?: Record<string, string> }.

Accessibility

Each field links its label, hint and error with htmlFor and aria-describedby; an invalid field has aria-invalid="true".
The status region uses role="alert" for errors and role="status" for everything else, so a result is announced without moving focus.
The form sets aria-busy while the action runs and the submit button is disabled, which prevents a double submit.
Because the form uses a real action, it works before hydration when your action is a server action.

Testing

The component ships with a Testing Library test (server-action-form.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.