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 when the user is toggling a binary setting and expects the change to take effect immediately.

Do

• Use when the choice is strictly binary (on / off, enabled / disabled).
• Use when the change should apply immediately without a save or submit action.
• Use when the control should remain visible to reflect the current state.
• Use for preferences, feature toggles, and visibility settings.

Don’t

• Don’t use for selecting one option among many — use RadioGroup.
• Don’t use for selecting multiple independent items — use Checkbox.
• Don’t use when changes are applied only after form submission.
• Don’t use for non-persistent or momentary actions.

Content Guidelines

Switch labels must clearly describe what is enabled when the switch is on. Users should understand the outcome of toggling the switch without guessing.

Do

• Write labels as states or features (e.g., “Tumma tila”, “Sähköposti-ilmoitukset”).
• Ensure the meaning of the on state is clear.
• Keep labels short, concrete, and easy to scan.
• Use helper text if the effect is complex or has consequences.
• Use consistent wording across similar switches.

Don’t

• Don’t use vague labels (e.g., “Käytössä”, “Vaihtoehto”, “Asetus”).
• Don’t phrase labels as actions (e.g., “Ota tumma tila käyttöön”).
• Don’t use long explanatory sentences as labels.
• Don’t rely on color alone to communicate the state.

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

• Toggling the switch applies the change immediately and persistently; no submit or confirmation is required.
• The switch always reflects the current state and should never appear “unset”.
• Disabled switches remain visible but are non-interactive.
• Disabled switches remain visible but are non-interactive.
• Supports both uncontrolled (defaultChecked) and controlled (checked + onChange) usage.
• Related content that appears or disappears based on the state should be placed close to the switch.
• In complex layouts, the label may be separated or wrapped as needed without changing behavior.

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.