Mutations and Forms
Validate a form, authorize a page action, call a service, and show pending, field-error and failure states.
Use a page action to change data from a page. The action validates input and checks access on the server, calls a service, then refreshes the page or redirects. useForm manages the submitted values and errors in React.
This guide adds a display-name form to the account summary page. It reuses the kit's real updateOwnName service; it does not write directly to Better Auth's tables.
1. Define the Request Schema
Create apps/web/lib/account-summary.schema.ts:
import * as z from 'zod';import { PROFILE_ERROR_CODES } from '@kit/better-auth/profile-rules';export const updateNameBody = z.object({ name: z.string({ error: PROFILE_ERROR_CODES.NAME_INVALID }),});The request schema checks the payload's shape. The existing account service applies the shared name rules and rate limits. For your own database records, derive validators from the Drizzle schema and select only writable fields; see Database and Services.
2. Add a Named Action
Add these imports and the actions export to the account summary's index.server.ts. Keep its loader, inferred Props, and head:
import { ValidationError } from 'void/handler';import { PROFILE_ERROR_CODES } from '@kit/better-auth/profile-rules';import { updateNameBody } from '#/lib/account-summary.schema.ts';import { setFlash } from '#/lib/flash.server.ts';import { updateOwnName } from '#/lib/profile.server.ts';export const actions = { updateName: defineHandler.withValidator({ body: updateNameBody })( async (c, { body }) => { requireSession({ c }); const result = await updateOwnName({ c, name: body.name }); const t = getServerTranslator({ c, namespace: 'app' }); if (result === 'invalid') { throw new ValidationError({ name: PROFILE_ERROR_CODES.NAME_INVALID }); } if (result === 'limited') { return c.text(t('accountSummary.tooManyChanges'), 429); } if (result === 'updated') { setFlash({ c, message: t('accountSummary.saved') }); } return c.redirect('/account-summary'); }, ),};The earlier file already imports defineHandler, getServerTranslator, and requireSession. The named action's URL is /account-summary?updateName. Send POST requests to it; loading a GET URL must not change data.
The redirect matters here: the account menu's user name comes from middleware-owned shared data. Returning nothing refreshes loader props, but does not rerun middleware. Redirecting gives both the page and shared user data a fresh request.
3. Connect the Form
Replace index.tsx with:
import { Form, useForm } from '@void/react';import { useTranslations } from '@kit/i18n/react';import { Button } from '@kit/ui/button';import { Field, FieldError, FieldLabel } from '@kit/ui/field';import { Input } from '@kit/ui/input';import { PageBody } from '@kit/ui/page';import { AppPageHeader } from '#/components/app-page-header.tsx';import type { Props } from './index.server';export default function AccountSummaryPage({ profile }: Props) { const t = useTranslations('app.accountSummary'); const tErrors = useTranslations('auth.errors'); const form = useForm( '/account-summary?updateName', { name: profile.name }, { throwOnError: false }, ); const nameError = form.errors.name; return ( <> <AppPageHeader /> <PageBody> <Form form={form} renderError={() => <p role="alert">{t('failed')}</p>} > <Field data-invalid={Boolean(nameError)}> <FieldLabel htmlFor="account-summary-name">{t('name')}</FieldLabel> <Input id="account-summary-name" name="name" autoComplete="name" value={form.data.name} onChange={(event) => form.setData('name', event.target.value)} aria-invalid={Boolean(nameError)} aria-describedby={nameError ? 'account-summary-name-error' : undefined} /> {nameError && ( <FieldError id="account-summary-name-error"> {tErrors(nameError)} </FieldError> )} </Field> <Button type="submit" disabled={form.pending}> {t(form.pending ? 'saving' : 'save')} </Button> </Form> </PageBody> </> );}Form defaults to POST and connects the inputs to useForm. Disable submission while form.pending is true. The keys used here were added in Create a Page; the existing auth.errors namespace translates the name validation code.
This compact example uses a generic translated failure message. The kit's components/profile-name-form.tsx is the fuller reference: it shows the server's translated 429 message, manages focus after failure, and renders a SubmitButton with success state.
Choosing the Submission API
| Need | Use |
|---|---|
| Form values, field errors and pending state | Form and useForm from @void/react |
| Awaitable mutation from a button or custom UI | action from @void/react |
| Complex form state | TanStack Form and @kit/ui/field, submitting to the same page action |
| Endpoint used outside this page | An API route |
For example, inside an event handler on this page:
import { action } from '@void/react';const result = await action('/account-summary?updateName', { data: { name: nextName },});if (!result.ok) { // Set your UI's translated failure state using result.error.}nextName is a value supplied by your UI. Expected action failures return ok: false; authentication and server failures can throw. Handle both when building a custom button. Do not treat React's form.post callback as an awaitable service API; use action() when you need a result.
Authorization and Failures
The server must authorize every mutation even if the button is hidden or the page sits under (app)/. Take the acting user from the session. For organization data, verify permissions and that the form's organization still matches the active organization; see Users and Permissions.
ValidationError produces field errors. Expected HTTP failures such as 409 or 429 become form errors. By default 401, 403, and server failures can throw; throwOnError: false retains them in form.error so your form can show a useful failure state.
Void protects page actions against cross-origin submissions. API routes have a separate kit origin check. A successful UI state is not proof of authorization: test direct requests and different users too.