Switch

Anatomy

import {Switch} from '@staffbase/design';

<Switch />

API reference

Switch

Renders a toggle that switches a single setting on or off. Pair it with Field to associate a label and description.

When to use

• When a single binary setting can be toggled on or off and the change takes effect immediately without a form submission.
• When the setting has a clear on/off meaning that works naturally in “Turn on [label]” or “Turn off [label]”.
• To present multiple related binary settings as a group under a shared topic heading.

When not to use

• Don’t use a Switch when the change requires a Save or Submit action to take effect — use a Checkbox inside a form instead.
• Don’t use a Switch for a non-binary or multi-value choice — use a Select or Radio instead.
• Don’t use a Switch to select items in a list or table — use Checkbox instead.

How to use

Structure

• Always pair a Switch with a visible label via Field.Label; never use a Switch without label text.
• Use Field.Description to add supporting text when the label alone does not fully explain the result or scope of the setting.
• Wrap the Switch and its labels in Field.Root to associate them accessibly.

States

• Use the disabled prop when the setting is temporarily unavailable; always provide surrounding context that explains why.
• Don’t use disabled as the permanent default — if a setting can never be changed, reconsider whether a Switch is the right component.
• Use readOnly when the value must be displayed but not modified, such as on a review or confirmation screen.
• The Switch takes effect immediately on toggle; no confirmation step is needed or expected by the user.

Switch groups

• Group related switches under a shared heading when multiple settings belong to the same topic.
• Don’t mix unrelated settings in one group — each group should represent a single coherent topic.
• Use a group description to explain the combined context or effect of all settings in the group.

Accessibility

• The Switch renders as role="switch" with aria-checked; always pair it with a visible Field.Label so assistive technology can announce the switch name.
• Don’t rely on Field.Description alone to identify the switch — the label must be self-explanatory without the description.
• The focus ring is provided by default; don’t suppress it with custom CSS.

Content & UX copy

• Write switch labels in Title Case with no colon or ending punctuation; keep to 2–3 words where possible and prefer noun phrases, for example “Notifications” or “Dark Mode”.
• Validate label wording by reading “Turn on [label]” and “Turn off [label]” aloud — if the result sounds natural, the label works.
• Write descriptions in sentence case and end with a period.
• If a description is an instruction, use the verb “select” rather than “click” or “toggle”.
• Write group labels in Title Case with no colon or ending punctuation, up to 2–3 words.
• Write group descriptions in sentence case and end with a period.