Skip to content

Design system

Documentation

DesignPatterns / Settings

Patterns / Settings

Beta

Settings

A settings pattern groups related preferences, makes unsaved changes visible, and reports the result of saving without moving the person away from context.

On this page

Examples

Save and recover changes

Compare a draft with its saved snapshot, validate fields, and recover from a failed save.

Workspace settings

Edit this local example. Saving updates its snapshot without making a backend request.

Workspace identity

This name appears in invitations and project headers.

Use a name your team will recognize.

Notifications

Choose where workspace activity replies should go.

Replies from activity emails use this address.

Workspace settings with draft, validation, saving, failure, and discard states

When to use

Use Settings when a person edits durable preferences rather than a one-off record. Give each group a short heading and description so a long page remains scannable. Keep a draft separate from the last saved values so Save and Discard have predictable results.

States

Settings pattern states and required feedback
StateWhat to showAction contract
changedA visible unsaved marker and available Save/Discard actions.Keep the person in the same group after editing.
savingA stable-size loading button and temporarily disabled fields and actions.Prevent repeated submits and edits that would make the result refer to old values.
savedA short status message near the actions.Update the saved snapshot only after the save succeeds.
errorA specific field error or a save error that keeps the draft.Correct the field or retry without losing other values.

Layout

  • Keep the section heading, explanation, fields, and actions in one surface when they belong to the same decision.
  • Disable Save when there are no changes or a save is already in flight; leave it available for a changed draft so validation can explain an invalid value.
  • Reserve room for inline errors so blur validation does not shift Save during a pointer click.
  • Confirm Discard before restoring the last saved snapshot. Cancel the confirmation without changing the draft.
  • Use a page for settings that need navigation or a multi-step workflow; do not force a large settings area into a Dialog.

The example saves only to a local snapshot and uses a timed, one-use failure fixture; it makes no backend request. The Preview and Code/Copy tabs use the same source file, src/components/design/examples/source/settings-pattern.tsx. This pattern has no property playground because it has no public pattern-level props. The isolated example has no route change; the Workspace Settings example shows a navigation guard for an unsaved draft.

Accessibility

  • Use headings for groups and keep their descriptions adjacent to the controls they explain.
  • Connect each visible label, description, and inline error to its control with a unique ID. Validate on blur and update an existing error as that field changes.
  • After an invalid Save, focus the first invalid field, including on repeated attempts. Do not move focus during typing or blur.
  • Move focus to the nearby status when saving disables Save, then update that aria-live="polite" region with the result without moving focus again.
  • Do not communicate unsaved, error, or success state by color alone; include text.
  • Keep the Discard confirmation keyboard operable, focus its non-destructive action first, and return focus to Workspace name after confirming Discard.

Do and don’t

Do

Show the changed state as soon as a value differs from the saved snapshot, preserve the draft after a failed save, and make recovery obvious.

Don’t

Auto-save every keystroke for consequential settings, discard edits without confirmation, or silently discard edits on navigation.

  • Field keeps each setting’s label and validation message connected.
  • Dialog is for a focused subtask, not a full settings page.
  • Button carries Save, Discard, and loading semantics.