Skip to content

Design system

Documentation

DesignPatterns / Forms

Patterns / Forms

Beta

Forms

A form pattern composes Field, Input, Button, and Card into a task that stays understandable when it grows beyond one screen.

On this page

Examples

Validation and recovery

A failed submit summarizes errors, moves focus to the summary, and links each message to its field.

Invite a teammate

Collect the minimum context before reviewing an invitation.

Contact details

Use a name and email the teammate will recognize.

Role and access

Explain why this person is joining before choosing permissions.

Keep this short; it appears in the invitation.

Teammate invitation form with validation summary and recovery links

When to use

Use this pattern for a form that collects related information and ends with an explicit review, save, or submit action. Keep domain rules in the screen or feature; the pattern only gives those rules a predictable structure.

Layout

  • Group fields by the decision the person is making, then separate groups with a quiet divider.
  • Use one visible label per control. Use a two-column row only when the fields remain easy to scan at the smallest supported width.
  • Keep the action row together at the end. The primary action says what will happen next; the secondary action cancels or returns without saving.
  • For a long form, keep the page or form body scrollable and leave the action row in a stable place. Do not hide the only submit action behind a clipped region.

Validation and recovery

Validate on submit when that is the least noisy moment that still helps the task. Show each error beside its field and repeat the current errors in a summary before the fields. After every invalid submit, move focus to the summary, including when the same errors remain. Each summary link focuses its matching field. Once an error appears, revalidate only that field as its value changes; keep errors in other fields and preserve the other entered values.

While the example reviews valid values, its fields are disabled and the Cancel action stops the simulated delay. Unmounting also clears that timer. The success status says the review is complete and explicitly states that no invitation was sent. The preview and Code/Copy tabs use the same source file, src/components/design/examples/source/forms-pattern.tsx; the file contains fixture behavior and makes no backend request. This pattern has no property playground because it has no public pattern-level props to explore.

Accessibility

  • Connect each FieldLabel to its control with htmlFor and a unique ID. Keep the field description in aria-describedby and include an error ID only while that error exists.
  • The summary is a named, focusable group. Focusing it announces the available errors; inline errors do not make a second live announcement, and remain available through the field’s description relationship.
  • Use aria-invalid only for an invalid value and mark genuinely required fields with required.
  • Announce completion with a role="status" message that describes the example’s actual action.
  • Test the full path with a keyboard: submit with errors, move through the error links, correct fields, and submit again.

Do and don’t

Do

Keep errors specific, linked to the fields they describe, and visible until the field value is valid or the form is reset.

Don’t

Put fetch calls or business validation inside Field, rely on a placeholder as the only label, or claim a simulated review sent data.

  • Field owns the label, description, and error relationship.
  • Input provides the single-line control and invalid/read-only states.
  • Button provides submit, cancel, disabled, and loading behavior.