Prepared Docs

Overview

ThemedSwitch is a compact sliding-track switch for two or three mutually exclusive options. Each option is icon-only and maps to a themed knob when active. With two options it renders a binary switch whose dimensions match the ui-core Switch exactly; with three options it renders a three-way toggle. The control always keeps one option selected and uses radio-group semantics under the hood.

When to use

Two or three peer options that must always have one active selection.
Icon-first compact controls where a themed knob reinforces meaning (for example on / off or yes / neutral / no).
Sliding-track switch visuals that still need proper radio-group keyboard and screen reader behavior.

When not to use

Plain binary on/off settings without theming — use Switch.
More than three options — use SegmentedControl or Select.
Optional selection where none may be active — use ToggleGroup.

Content guidelines

Provide a concise label for every option; labels become the accessible names because the control is icon-only.
Use parallel meaning across the options (for example on / off, or approve / unset / reject).
Pair knob themes with icons so state is not conveyed by color alone.

Behavior and states

Always one selected. The control does not support an empty selection state.
Morphing knob icon. The active knob icon crossfades between options using the shared Icon morph tooling.
Themed knobs. Each option can set a knob of KnobType.Switch, Neutral, Success, or Error, driving the knob fill, including success and destructive gradients.
Switch parity. A two-option ThemedSwitch matches the Switch track width, height, and thumb size exactly.
Reduced motion. Knob slide and icon morph both respect prefers-reduced-motion: reduce.

Best practices

Provide ariaLabel or labelledBy on the root so the group purpose is announced.
Default to the safest or most common option when the user has not chosen yet.
Use ThemedSwitchSize.Medium or Large for primary controls; pair distinct icons with knob themes.

Don't

Use more than three options in one instance.
Rely on color alone to communicate meaning — keep distinct icons for each position.
Use Small as the only size for high-frequency actions unless surrounding layout provides adequate target spacing.

Accessibility

Each option exposes radio semantics; arrow keys move selection; names come from option labels. The component ships focus, contrast, reduced-motion, and forced-colors hardening for WCAG 2.2 AA. See Accessibility for the full contract, including target-size guidance.

Switch for plain binary on/off settings.
SegmentedControl for labeled multi-segment controls.
ToggleGroup when deselecting all options is valid.

Accessibility / Testing with Screen Readers

Themed Switch / API and Development

Overview

When to use

Two or three peer options that must always have one active selection.
Icon-first compact controls where a themed knob reinforces meaning (for example on / off or yes / neutral / no).
Sliding-track switch visuals that still need proper radio-group keyboard and screen reader behavior.

When not to use

Plain binary on/off settings without theming — use Switch.
More than three options — use SegmentedControl or Select.
Optional selection where none may be active — use ToggleGroup.

Content guidelines

Provide a concise label for every option; labels become the accessible names because the control is icon-only.
Use parallel meaning across the options (for example on / off, or approve / unset / reject).
Pair knob themes with icons so state is not conveyed by color alone.

Behavior and states

Always one selected. The control does not support an empty selection state.
Morphing knob icon. The active knob icon crossfades between options using the shared Icon morph tooling.
Themed knobs. Each option can set a knob of KnobType.Switch, Neutral, Success, or Error, driving the knob fill, including success and destructive gradients.
Switch parity. A two-option ThemedSwitch matches the Switch track width, height, and thumb size exactly.
Reduced motion. Knob slide and icon morph both respect prefers-reduced-motion: reduce.

Best practices

Provide ariaLabel or labelledBy on the root so the group purpose is announced.
Default to the safest or most common option when the user has not chosen yet.
Use ThemedSwitchSize.Medium or Large for primary controls; pair distinct icons with knob themes.

Don't

Use more than three options in one instance.
Rely on color alone to communicate meaning — keep distinct icons for each position.
Use Small as the only size for high-frequency actions unless surrounding layout provides adequate target spacing.