Switch

<Switch> toggles between two states, like on and off. Unlike a checkbox, a switch takes effect right away, no form submission needed. If you've used a light switch, you get the idea.

The component has a track (the pill), a thumb (the circle that slides), a label, and an optional description underneath.

Anatomy

The switch is composed of:

• Track: the background pill representing the two states
• Thumb: the circle that slides between on and off
• Label: text describing what the switch controls
• Description (optional): extra context below the label

Appearance

The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.

The Switch component provides two layout variants for different placement contexts.

Usage

Switches are for standalone settings where flipping the control applies the change right away. No save button, no form submission. The change is live the moment you toggle.

You'll find them on settings pages, notification preferences, feature toggles, and privacy panels. Each switch should control one independent setting. Toggling one should never affect another.

Use the default variant when the switch is embedded inside another element, such as a card or list item. For standalone settings pages, use variant="settings". See Settings and preference below.

import { Badge, Card, Inline, Stack, Switch, Text } from '@marigold/components';export default () => (  <Stack space={4}>    <Card stretch>      <Card.Content>        <Inline alignY="center" space={4}>          <Stack space="tight" stretch>            <Inline space={2} alignY="center">              <Text weight="bold">Weekly digest</Text>              <Badge variant="success">Active</Badge>            </Inline>            <Text variant="muted" size="sm">              A summary of activity from the past week, delivered every Monday.            </Text>          </Stack>          <Switch label="Active" defaultSelected />        </Inline>      </Card.Content>    </Card>    <Card stretch>      <Card.Content>        <Inline alignY="center" space={4}>          <Stack space="tight" stretch>            <Text weight="bold">Slack integration</Text>            <Text variant="muted" size="sm">              Post updates to your team's Slack channel automatically.            </Text>          </Stack>          <Switch label="Active" />        </Inline>      </Card.Content>    </Card>  </Stack>);

Default a switch to on when the setting reflects an active, recommended, or previously saved state. Default to off when the feature is opt-in or when turning it on has consequences the user should consciously choose. When in doubt, default to off.

Labeling

Labels should name the setting, not the action of toggling it. Keep them to one to three words. The switch itself already says on/off, so verbs like "Enable" or "Allow" are redundant. Frame labels so that on means the active, expected behavior.

Description

Add a description when the label alone doesn't explain what toggling actually does. This is most useful for settings that have consequences ("deletes all data") or that use technical language the user might not recognize.

import { Switch } from '@marigold/components';export default () => (  <Switch    label="Enable notifications"    description="Receive alerts when important events occur."  />);

Error

Set error to mark the switch as invalid and pass an errorMessage to explain what needs to change. The error message replaces the description while error is set, and it is announced to screen readers via aria-describedby.

import { Switch } from '@marigold/components';export default () => (  <Switch    label="Enable notifications"    error    errorMessage="You must enable notifications to continue."  />);

Settings and preference

On dedicated settings or preference pages, switches appear as a vertical list where the label is the primary scanning element. Use variant="settings" for this layout: the label sits on the left and the toggle on the right.

import { Divider, Headline, Stack, Switch } from '@marigold/components';export default () => (  <Stack space={6}>    <Stack space={4}>      <Headline level={3} size="level-3">        Notifications      </Headline>      <Switch        variant="settings"        label="Email notifications"        description="Receive emails when someone mentions you or replies to your comments."        defaultSelected      />      <Divider />      <Switch        variant="settings"        label="Marketing emails"        description="Get updates about new features and promotions."      />      <Divider />      <Switch        variant="settings"        label="Weekly report"        description="A summary of your team's activity, sent every Monday morning."        defaultSelected      />    </Stack>    <Stack space={4}>      <Headline level={3} size="level-3">        Security      </Headline>      <Switch        variant="settings"        label="Two-factor authentication"        description="Require a verification code when signing in from a new device."        defaultSelected      />      <Divider />      <Switch        variant="settings"        label="Login alerts"        description="Get notified when your account is accessed from an unrecognized device."        defaultSelected      />    </Stack>  </Stack>);

The label-left layout works because users need to understand what a setting controls before deciding whether to change it. The two-column rhythm gives a readable label column scanned top-to-bottom and a uniform action column glanced at only to check or change state. On mobile, the toggle also lands near the right thumb for easier one-handed reach.

Group switches by topic with a section heading. Each row should control one independent setting. Toggling one should never silently affect another.

A switch is built around the light-switch metaphor: flipping it is the change, not a request to make the change. The component renders with role="switch", which screen readers announce as "on" or "off" the moment the user activates it. Both the visual and accessibility contract say the new state is true now.

Putting a switch inside a <Form> with a Save button breaks both contracts. The toggle visually flips and the screen reader announces "on", but the underlying state is not actually saved until the user submits. This is why production auto-save settings (iOS Settings, GitHub repo Features, Linear, Vercel, Notion) use switches, while save-bound admin forms (WordPress, Jira, Salesforce) use checkboxes.

Choosing the right control

Switches, checkboxes, and toggle buttons can look similar but work differently. The main distinction is when the change takes effect.

A switch always applies its change the moment you toggle it. There is no save step. This makes switches a poor fit inside forms where other fields require submission. If a page has a "Save" button, the switch creates ambiguity: did that toggle already apply, or does it wait for Save? Use a checkbox in those situations.

A toggle button is for temporary states tied to the current view, like bold in a text editor or switching between grid and list layout. Unlike a switch, a toggle button doesn't persist a setting.

Also watch out for opposing options. Two switches like "Light mode" and "Dark mode" side by side don't make sense because they aren't independent. Use a single switch or a radio group instead.

Props

Switch

Alternative components

• Checkbox: one or more selections in a form, applied on submission.
• Radio: a single choice from a list of mutually exclusive options.
• ToggleButton: a temporary mode or view state in the current context.

Related