In progress

Switch

A Switch toggles between two mutually exclusive states (“on” / “off”) and applies the change immediately.

• Figma
• Storybook
• Edit this page
• Create a new issue

Enable dark mode

Code example

import { Switch } from '@yleisradio/yds-components-react';

<Switch id="darkmode" name="darkmode" label="Enable dark mode" defaultChecked />

Why to use

Switch communicates an instant, persistent state change. Use it when the user expects something to happen immediately after toggling (e.g., enable/disable a feature or visibility), and when the two states are clear opposites.

When to use

Use a Switch for immediate, binary state changes where the user expects something to happen right away (e.g., enable/disable, show/hide) and the control should always remain visible to indicate the current state. If the task involves choosing one option among many, selecting multiple items, or submitting changes later, prefer Radio or Checkbox patterns instead.

Do

• Use when the choice is binary and mutually exclusive (on/off, show/hide).
• Ensure the effect is immediate—no separate “Save” or submit step.
• Keep the control visible so the current state is always clear.
• Provide a clear label describing the effect when switched on.
• Set an appropriate default state.
• Place dependent content close to the Switch if it appears/disappears.

Don’t

• Don’t use for multi-choice inputs — use Radio Group (single choice) or Checkbox (multiple choices).
• Don’t require a separate submit after toggling.

Key Props

Use the following props to customize the Switch component to your needs.

label

Descriptive text for the setting—phrase its meaning in the ON state.

Type	Example	Description
string	Enable usage analytics	Visible label describing the effect when enabled.

Code example

<Switch id="metrics" name="metrics" label="Enable usage analytics" defaultChecked />

defaultChecked

Uncontrolled initial state.

Type	Example	Description
boolean	Auto sync	Sets starting state to ON without manual state management.

Code example

<Switch id="auto-sync" name="auto-sync" label="Auto sync" defaultChecked />

checked

Controlled state—must pair with onChange.

Type	Example	Description
boolean	Enable beta	Explicitly sets state; component is read-only without onChange.

Code example

const [enabled, setEnabled] = useState(false);
<Switch
  id="beta"
  name="beta"
  label="Enable beta features"
  checked={enabled}
  onChange={(e) => setEnabled(e.currentTarget.checked)}
/>

isDisabled

Non-interactive, dimmed styling.

Type	Example	Description
boolean	Auto sync	Temporarily prevents user interaction.

Code example

<Switch id="sync" name="sync" label="Auto sync" isDisabled />

Behavior

• Changes are immediate and persistent; no submit is required.
• Provide a default state; the control should never look “unset”.
• Keep related content near the switch if it appears/disappears based on state.
• Disabled switches remain visible but non-interactive.
• Supports uncontrolled (defaultChecked) and controlled (checked + onChange) usage.
• For complex layouts, you can separate or wrap the label as shown above.

Accessibility

• Every Switch must have a visible or programmatically associated label.
  (WCAG 3.3.2 — Labels or Instructions)
• Use labels that clearly describe the effect when turned on (e.g., “Enable notifications”).
  (WCAG 2.4.6 – Headings and Labels)
• Keyboard: Tab/Shift+Tab moves focus; Space toggles the state; Enter also toggles in many browsers.
  (WCAG 2.1.1 — Keyboard)
• If helper or error text is present, link via aria-describedby so it’s announced by assistive tech.
  (WCAG 1.3.1 — Info and Relationships)

Implementation examples

Accessibility naming without label

You may use aria-label / aria-labelledby for programmatic naming.

Code example

<Switch id="updates2" name="updates2" label="" aria-label="Enable updates" />

API Reference

Props

The Switch component accepts all standard HTML <input> attributes in addition to the following props:

Prop	Type	Required	Default	Description
isDisabled	boolean	No	false
name	string	Yes	—
label	string	Yes	—
labelOptions	FormElementLabelDSProps	No	{}

Type Definitions

export interface SwitchDSProps {
  isDisabled?: boolean;
  name: string;
  label: string;
  labelOptions?: FormElementLabelDSProps;
}

export type SwitchProps = InputHTMLAttributes<HTMLInputElement> & SwitchDSProps;

Related Components

• Radio: Single required choice among options.
• Checkbox: Independent multi-select options.
• TextInput: For text entry when changes saved on submit.