Granularity
⌘K
v1.1.1

Settings

  • Entering data
  • 3 min
  • components: 8
  • pairs: 3

Every setting answers one question first — does it apply now or on save. Everything else about the screen follows from that answer.

Reviewed 2026-09-05

On this page

What it solves

A settings screen looks like a form and behaves like a control panel, and mixing the two is why they are so often confusing.

One question decides everything else: does the change apply immediately, or on save? Immediate settings need no buttons and no unsaved state; deferred ones need both, and need to say so. A screen that mixes them without a visible line between the two teaches people that neither can be trusted.

Anatomy

Choose the control by the shape of the choice, not by how much room it takes. The library states the condition for each:

  1. The setting turns on right away — GrSwitch. It is a switch precisely because there is no «apply»: flipping it is the action.
  2. Up to seven options, all visible — GrRadioGroup. One choice out of a set you can read at a glance.
  3. Switching the view of the same thing — GrSegmented. Not a setting of the object but of how you are looking at it.
  4. Several values from a short set — GrCheckboxGroup. One field, many values, shared state.
  5. A form field with a list of values — GrSelect. When the set is too long to show open.
  6. The exact number does not matter — GrSlider. A value you feel rather than type; if the number is precise, it belongs in a field.
  7. The form is long — GrFormSection. Sections make a settings page scannable; without them it is a list to be read from the top.
  8. The action is irreversible — GrConfirmDialog. Deleting a workspace does not belong among the checkboxes.

Example

Do and don’t

Do — Immediate settings apply immediately

A switch changes the thing the moment it is flipped, and the screen shows the result. No «save» for switches: the button would be asking the person to confirm what they already did.

Don’t — A save button over a page of switches

If the button exists, the switches were not switches — they were a form drawn with switch-shaped controls. The person flips three, walks away, and loses all three without being told.

Do — Say the state out loud, not only in colour

«Notifications: on» beats a coloured track. GrSwitch is a native <button role="switch"> — the state is announced, and Space or Enter toggles it, which is what a keyboard user will try.

Don’t — A switch for something that is not binary

«Theme» has three values — light, dark, system — and a switch has two. It becomes a switch plus a hidden third state, and the hidden one is the default. Three options are GrRadioGroup or GrSegmented.

Do — Separate the dangerous part

Deleting an account, revoking every token, transferring ownership: below the settings, visually apart, with GrConfirmDialog carrying the consequence in words. The distance is part of the design.

Don’t — A dangerous action styled like the rest

A red button in the row of ordinary ones is one mis-click away from irreversible. Colour is a warning only to people who see it, and nobody reads a screen they have visited fifty times.

Accessibility

A switch is a switch, a radio group is a radio group. The roles differ, and so does the keyboard: Space or Enter toggles a switch; arrows move within a radio group and the choice moves with the focus. Drawing one as the other means the announcement will not match the behaviour.

GrSegmented walks on both axes. Left and right, up and down, whatever the orientation — because APG requires it of a radiogroup, and a person who tries the other pair should not find a dead end.

Grouping must be real. GrFormSection produces a group with a heading, so a screen reader can say which section a control belongs to. Visual grouping alone is grouping only for those who can see it.

The hardest part of a settings screen is not on this page: it is deciding which settings should exist. Every option is a question the product refused to answer on the user’s behalf.

Components in this pattern

The list is built from frontmatter, not from links in the prose: renaming a slug does not lose it.

Keyboard

Contracts come from the library. The pattern does not restate them — it points at them.