Form

Server component with client leaf Form, SubmitButton

ImportCopy Anchor Link

import { Form, FormMessage, SubmitButton } from '@nizivo/react/form';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/alert.css and @nizivo/react/css/base.css and @nizivo/react/css/button.css
import '@nizivo/react/css/form.css';

Static or interactiveCopy Anchor Link

Server, with two client parts. FormMessage renders on the server and ships no client JavaScript; Form and SubmitButton are client leaves, imported from @nizivo/react/form beside it. Every Field already works without Form: native validation is inline and focuses the first invalid control, and an error passed to a Field's error shows with no client code of Form's. Use Form when errors come back from a server action and you want them matched to Fields by name. How to choose.

In a client app (a Vite or React Router single-page app, or a 'use client' file) it is an ordinary React component: event handlers, refs and state work as usual. In a client app.

Errors from a server actionCopy Anchor Link

Pass the action's field errors to errors, keyed by each Field's name, as z.flattenError(error).fieldErrors returns them: a message, or a list of messages, of which the first shows. A nested name is one key, written as the Field's name is (items.0.title). Each error goes through the Field's one error channel: the Field's own error prop wins over it, and it wins over a native validation message.

'use client';
const [state, action] = useActionState(saveProduct, {});
<Form action={action} errors={state.fieldErrors}>
  <FormMessage>{state.formError}</FormMessage>
  <Field name="title" label="Product title" required>
    <Input defaultValue={state.values?.title} />
  </Field>
  <SubmitButton>Save</SubmitButton>
</Form>;

• Put name on the Field, not only on the control: Form matches by the Field's name. A Field with a function child (zero JS) or a FieldStatic reads no Form errors; pass its error.
• Focus. Each new errors object (by identity) moves focus to the first invalid control in page order, after the errors render, so the control is read with its message. The first render moves no focus, so a page that arrives with errors does not take focus as it loads.
• Edits. Once the user changes a control's value, its error from the server is stale, so it is hidden until the next errors object.
• Echo the values back as defaultValue: React resets uncontrolled fields after an action, even one that returns errors.

Error summaryCopy Anchor Link

summary adds GOV.UK's error summary at the start of the form: a critical Alert titled "There is a problem" (labels.summaryTitle) with one link per error, in page order. New errors focus the summary instead of the first invalid control, and a link focuses its control. Use it on long forms, where the first error may be off screen. Its links point at the controls once the form has hydrated.

SubmitButtonCopy Anchor Link

A primary Button with type="submit" that is pending while its form's action runs, read with React's useFormStatus: the spinner shows, it stays focusable with aria-disabled, and it cannot submit again. Only an action passed as a function (<Form action={fn}>) reports a status, never a URL. pending forces the state, for example while a client handler awaits something else.

FormMessageCopy Anchor Link

The form-level message, for failures no Field owns (network, permission, a conflict) and for success. Render it always and change only its children: the live container is in the page from the first render, empty, so a message added later is announced. critical (the default) is role="alert"; success, info and warning are role="status".

ExamplesCopy Anchor Link

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { Input } from '@nizivo/react/input';
import { Form, SubmitButton } from '@nizivo/react/form';

export function FormExample(): JSX.Element {
  return (
    <Form style={{ display: 'grid', gap: 16, maxInlineSize: 360 }}>
      <Field
        name="title"
        label="Product title"
        required
        messages={{ valueMissing: 'Enter a product title.' }}
      >
        <Input />
      </Field>
      <Field name="sku" label="SKU" description="Letters and numbers, as printed on the label.">
        <Input />
      </Field>
      <div>
        <SubmitButton>Save</SubmitButton>
      </div>
    </Form>
  );
}

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { Input } from '@nizivo/react/input';
import { Form, FormMessage, SubmitButton } from '@nizivo/react/form';

export function FormServerErrorsExample(): JSX.Element {
  return (
    <Form
      summary
      errors={{
        title: 'Enter a product title.',
        price: ['Enter a price above 0.', 'Enter a number.'],
      }}
      style={{ display: 'grid', gap: 16, maxInlineSize: 360 }}
    >
      <FormMessage>
        We could not save the product. Check the fields below and try again.
      </FormMessage>
      <Field name="title" label="Product title" required>
        <Input />
      </Field>
      <Field name="price" label="Price" required>
        <Input inputMode="decimal" prefix="₹" defaultValue="0" />
      </Field>
      <div>
        <SubmitButton>Save</SubmitButton>
      </div>
    </Form>
  );
}

import type { JSX } from 'react';
import { FormMessage } from '@nizivo/react/form';

export function FormMessageExample(): JSX.Element {
  return (
    <div style={{ display: 'grid', gap: 12, maxInlineSize: 420 }}>
      <FormMessage tone="success">Product saved.</FormMessage>
      <FormMessage tone="critical" title="Not saved">
        Your session ended. Sign in again to save the product.
      </FormMessage>
      <FormMessage tone="info">{null}</FormMessage>
    </div>
  );
}

PropsCopy Anchor Link

Other exportsCopy Anchor Link

FormErrorValue type

import type { FormErrorValue } from '@nizivo/react/form'

One Field's errors: a message, or several (the first is shown), or none.

type FormErrorValue = string | readonly string[] | null | undefined

FormErrors type

import type { FormErrors } from '@nizivo/react/form'

Errors keyed by the Field's name, as a server action returns them (Zod's z.flattenError(error).fieldErrors, or Conform's and TanStack Form's issues mapped to text). A nested name is one key, written as the Field's name is: items.0.title. Serialisable.

type FormErrors = Readonly<Record<string, FormErrorValue>>

FormLabels type

import type { FormLabels } from '@nizivo/react/form'

Form's own strings (§16.4): serialisable, English defaults.

Name	Type	Default	Description
summaryTitlerequired	string	'There is a problem'	The error summary's title.

FormMessageProps type

import type { FormMessageProps } from '@nizivo/react/form'

The props of FormMessage, listed above.

FormMessageState type

import type { FormMessageState } from '@nizivo/react/form'

The render state of FormMessage, listed above.

FormMessageTone type

import type { FormMessageTone } from '@nizivo/react/form'

Alert's tones. critical is a role="alert" container; the others are role="status".

type FormMessageTone = AlertTone

FormProps type

import type { FormProps } from '@nizivo/react/form'

The props of Form, listed above.

SubmitButtonProps type

import type { SubmitButtonProps } from '@nizivo/react/form'

The props of SubmitButton, listed above.

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-form-summary, .nz-form-summary-link, .nz-form-summary-list.

AccessibilityCopy Anchor Link

These parts are interactive. Each gets the focus outline and touch-action rule from @nizivo/react/css/base.css (the nz.base layer), so the floor survives a restyle:

• form-summary: draws the focus outline itself on keyboard focus.
• form-summary-link: draws the focus outline itself on keyboard focus.

KeyboardCopy Anchor Link

Source: a native <form> (form.client.tsx) and SubmitButton's native <button type="submit">. The browser lane (test/browser/form.spec.tsx) checks native validation inside a Form, an action's errors by name with focus on the first invalid control, the summary's focus and links, and SubmitButton's pending state.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: none
• Ghost masters: none