Skip to contentSkip to navigation
DocsDocs

Settings

Let people change how the application works for them, and see each change apply.

BetaSince 1.0.0
On this page

Overview

Show code, ImmediateToggles.tsx

Variants

Save a section

Settings that only make sense together wait for a Save button.

  • A Badge marks the section while it holds unsaved changes.
  • Cancel puts back what was saved.
Show code, SaveSection.tsx

Appearance

The theme applies at once. The scale, system, comfortable or compact, is one for the whole application: it never changes for one page or one section.

Show code, AppearanceChoice.tsx

Danger zone

The last section, apart from the rest, holds what deletes or ends the account or the workspace, confirmed as destructive actions are.

Show code, DangerZone.tsx

Anatomy

  1. Section heading

  2. Setting

  3. Switch

  4. Danger zone

Show code, SettingsAnatomy.tsx

Behaviour

Confirmation

A switch shows its own state, so most changes need no message. A toast says only what people can't see on the page, such as becoming visible in a directory.

Rules

Each setting either applies the moment it changes, or waits with the settings it depends on for a Save button, and the two never share a section.

Use it when

  • A preference that applies at once, such as a notification or the theme
  • A few related values saved together, such as a profile

Built from

Page, NavigationDrawer, Surface, List, DescriptionList, Switch, Select, Radio, TextField, Badge, Button, ConfirmDialog

DoSwitches that apply the moment they change, with no Save button.
Show code, SwitchesApplyAtOnce.tsx
Don’tSwitches that wait for Save: people can't tell which changes are kept.
Show code, SwitchesWithSave.tsx

Sections

Group settings by what people want to do, not by how the data is stored. A long page lists its sections in a NavigationDrawer beside them, or gives each its own page.

Content

Name a section after what people want to do, such as "Email notifications", not "User preferences". Label each setting as a Switch's label is written, with its effect in the row's detail.

Accessibility

Focus and keyboard

Space turns a focused switch on or off, and focus stays, since nothing moves.

  • Save keeps focus on its button and says the outcome in a status.
  • A refused Save moves focus to the field to fix.
  • The danger zone's dialog takes focus to Cancel and gives it back as it closes.

Related