# Mutations and Forms

> Validate a form, authorize a page action, call a service, and show pending, field-error and failure states.

*Canonical: https://makerkit.dev/docs/void-cloudflare/development-guide/mutations-and-forms*

---

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](./data-fetching). 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`:

```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](./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`:

```ts
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:

```tsx
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](./pages-and-routing); 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](./api-routes) |

For example, inside an event handler on this page:

```ts
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](./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.

---

**Next:** [Users, Sessions and Permissions →](./users-and-permissions)
