BridgeHandbookDraft
For agents
Menu
ExperimentalatomInputs

Switch

An on/off setting that takes effect immediately.

import { … } from "@brdgapp/ui/components/switch"

Usage

Switch turns a setting on or off, and the change takes effect immediately, with no Save button. The usual mistake is using it inside a form that saves later: a switch promises an instant change.

When to use

  • A setting that applies the moment it's flipped: notifications, visibility, appearance options.

When not to use

  • Inside a form that saves with a button. Use a checkbox. Use Checkbox instead.
  • For choosing between two named modes (Light / Dark). Use SegmentedControl instead.

Fill with -solid

Anything with white text on a colored fill uses --primary-solid or --danger-solid. The brand --primary and --error are for text, icons and focus rings; as fills they fail contrast (white on --error is 4.41:1).

Anatomy

  1. Track. 36 × 20px pill. Off: --surface-tertiary. On: --primary-solid.

  2. Thumb. A 16px white circle that slides.

Examples

A setting

Labeled by the visible text.

Show my ICP on my profile

People who view your profile see who you want to meet.

States

States

RestFocusDisabled
Off
On
StateWhat happens
OffGrey track, thumb left.
OnBlue track, thumb right.
Focus visible2px blue ring with a 2px offset.
Disabled40% opacity.

Behavior

  • Built on Base UI Switch: role="switch" with aria-checked.
  • Controlled: you pass checked and onChange. Save the change straight away, and show if it fails.

Do and don't

Do

Label the setting, not the action: "Show my ICP on my profile".

Don't

Label it "Turn on" or "Enable".

Content

  • The label describes the setting when it's on.

Accessibility

  • A name is required: aria-label, or aria-labelledby pointing at the visible label (preferred).
  • The off track is low-contrast against the page (non-text contrast under 3:1). The thumb's position and the label carry the meaning; see Known gaps.
KeysAction
SpaceEnterFlip the switch.

API reference

Switch

The toggle, built on Base UI Switch.

PropTypeDefaultDescription
checkedboolean—On or off.
onChange(checked: boolean) => void—Called with the new value.
disabledbooleanfalseCan't be changed.
aria-labelstring—The name, when there's no visible label.
aria-labelledbystring—The id of the visible label.
classNamestring—Layout only.

Lineage

What it's built from and where it's used, read from the code. When you change it, check these too.

Built from
Nothing else in the package
Used by components
None
Used in patterns
Forms and validationSaving and unsaved changes
Used in templates
Settings form

Known gaps

Where the code still differs from the system. Follow the system, not the gap.

  • The off track (--surface-tertiary on white) is under the 3:1 non-text contrast guideline.
  • Bridge OS fills the on track with --primary; the package uses --primary-solid like every other blue fill.

Sources

  • Bridge OS components.md → Switch; src/components/ui/switch.tsx.