Version: 3.5.13

Switch

Switches allow users to toggle a single option on or off. They provide immediate visual feedback and are ideal for settings, preferences, and binary choices.

Overview

Switches are toggle controls that allow users to turn an option on or off. Unlike checkboxes, switches are typically used for settings and preferences that take effect immediately, rather than for form selections.

All switch styles are built using design tokens, ensuring consistency across themes and hues. Use the interactive playground below to explore all available combinations.

Interactive Playground

Use the controls to customize the switch and see how it looks in real-time. Toggle between themes and hues to see how switches adapt to different contexts.

Color
Checked
Show Icons
Label
<Switch />
Anatomy

A switch consists of a track container and a handle that moves between positions. Switches can optionally include icon containers for visual context.

Unchecked

Checked

Track52px width, rounded-full, 2px padding
Handle24px × 24px, moves left (off) or right (on)
IconsOptional SunIcon and MoonIcon in 32px containers
Variants & States

Switches come in different states and can optionally include icons to fit various use cases.

Unchecked

Default off state. Handle positioned on the left with neutral background.

Checked

On state with primary background color. Handle positioned on the right.

Hovered

Hover state provides visual feedback when the user hovers over the switch.

Focused

Focus state indicates keyboard navigation focus with a distinct border color.

Pressed

Pressed state shows active interaction feedback when the switch is being pressed.

Disabled

Disabled state prevents interaction. Can be disabled in checked or unchecked states.

With Icons

Switch with icon containers for visual context, useful for theme toggles.

With Icons (Checked)

Switch with icons in checked state showing the active state.

Usage Guidelines
Do
  • Use switches for settings and preferences that take effect immediately.
  • Use switches for binary on/off choices.
  • Provide clear labels that describe what the switch controls.
  • Use switches with icons for theme toggles (light/dark mode).
  • Ensure switches are clearly visible and easy to interact with.
  • Use switches in settings panels and preference dialogs.
Don't
  • Don't use switches for form selections (use checkboxes instead).
  • Don't use switches for immediate actions (use buttons instead).
  • Don't use switches without clear labels or context.
  • Don't use switches for mutually exclusive options (use radio buttons instead).
  • Don't disable switches without explaining why.
  • Don't use too many switches in a single view.
Accessibility
  • Always associate switches with labels using proper HTML structure or ARIA attributes.
  • Ensure sufficient color contrast between switch states and backgrounds.
  • Provide keyboard navigation support (Space to toggle, Tab to navigate).
  • Use semantic HTML elements or proper ARIA roles for switches.
  • Ensure switches are large enough to be easily clickable (minimum touch target size).
  • Provide clear visual feedback for all interactive states (hover, focus, checked).
  • Announce state changes to screen readers when switches are toggled.
API Reference

Switch component props and types.

SwitchProps
interface SwitchProps { checked?: boolean; status?: "default" | "hovered" | "focused" | "pressed" | "disabled"; showIcons?: boolean; onChange?: (checked: boolean) => void; }
Props
checked
boolean
false
Whether the switch is checked (on). When true, handle is positioned on the right.
status
"default" | "hovered" | "focused" | "pressed" | "disabled"
"default"
Interactive state of the switch. Controls visual styling for different interaction states.
showIcons
boolean
false
Whether to show icons. When true, displays sun and moon icons in containers for visual context.
onChange
(checked: boolean) => void
—
Callback function called when switch state changes.
Usage Examples

Copyable code snippets for common switch use cases.

Basic Switch
import { Switch } from 'beacon-ui'; <Switch />
Checked Switch
import { Switch } from 'beacon-ui'; <Switch checked />
Disabled Switch
import { Switch } from 'beacon-ui'; <Switch checked status="disabled" />
Theme Switch
import { Switch } from 'beacon-ui'; <Switch showIcons />
Switch with Label
import { Switch } from 'beacon-ui'; <label style={{ display: "flex", alignItems: "center", gap: "var(--spacing-200)" }}> <span>Enable notifications</span> <Switch checked /> </label>
Switch Group
import { Switch } from 'beacon-ui'; <div style={{ display: "flex", flexDirection: "column", gap: "var(--spacing-300)" }}> <label style={{ display: "flex", alignItems: "center", gap: "var(--spacing-200)" }}> <span>Email notifications</span> <Switch checked /> </label> <label style={{ display: "flex", alignItems: "center", gap: "var(--spacing-200)" }}> <span>Push notifications</span> <Switch /> </label> </div>