Switch

View source on GitHub
See recent changes on GitHub

Use Switch for single cell options that can be turned on and off only. If you have a cell with multiple options that can activated, consider using Checkbox.

Switch supports right-to-left(RTL) language locales layout (auto flip on RTL locales like Arabic).

also known as Toggle, Slide Toggle

Figma:
Ready
Responsive:
Ready
Adaptive:
N/A

Props

Component props
Name
Type
Default
id
Required
string
-

A unique identifier for the element.

onChange
Required
(arg1: { event: React.ChangeEvent<HTMLInputElement>; value: boolean }) => void
-

Callback triggered when the user interacts with the input.

disabled
boolean
false

Indicates if the input is currently disabled. See Switch combinations for more details.

name
string
-

A unique name for the element.

switched
boolean
false

Indicates the current value of the input. See Switch combinations for more details.

Usage guidelines

When to use
  • For a binary option that can be either active or inactive.
  • Typically used on mobile, where toggling the Switch takes immediate effect.
When not to use
  • Choosing between related options. Each Switch should be considered a solitary, standalone option. For multiple, related choices, use Checkboxes or RadioGroup instead.

Best practices

Do

Use a label to give Switch context when possible.

Don't

Truncate label text. Instead, allow it to wrap to form another line.

Do

Communicate why a switch is disabled and how to enable it if possible.

Don't

Use alternative styling to represent the functionality of a switch. Use Switch instead.

Accessibility

Switches should have Labels that can be read by screen readers, and that can be clicked or tapped to make it easier for users to select and deselect. Make sure Label has an htmlFor prop that matches the id on the Switch. Test that the Switch and Label are properly connected by clicking or tapping on the label and confirming that it activates the Switch next to it.

Keyboard navigation

Switch has conventional keyboard support.

  • Users relying on the keyboard expect to move focus to the Switch by using the tab key or shift+tab when moving backwards.
  • Setting disabled will prevent Switch from receiving keyboard focus or input.
  • Once focused, the Space key toggles the Switch.

Localization

Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.

Be sure to localize label and subtext. Be mindful of label length so that it doesn’t truncate in languages with lengthier character counts.

Variants

With a label

Whenever using Switch, always use a Label with it to make your component accessible.

import { useState } from 'react';
import { Flex, Heading, Label, Switch, Text } from 'gestalt';

export default function SwitchExample() {
  const [switched1, setSwitched1] = useState(false);
  const [switched2, setSwitched2] = useState(true);
  const [switched3, setSwitched3] = useState(true);

  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Flex direction="column" gap={2} maxWidth={300} width="100%">
        <Heading size="300">Tune your home feed</Heading>
        <Text>
          Turn off any boards that you don&apos;t want us to use for your home
          feed recommendations
        </Text>
        <Flex direction="column" gap={4}>
          <Flex alignItems="center">
            <Flex.Item flex="grow">
              <Label htmlFor="boardfood">
                <Flex direction="column" gap={1}>
                  <Text>Food</Text>
                  <Text size="100">55 pins · 1 section</Text>
                </Flex>
              </Label>
            </Flex.Item>
            <Switch
              id="boardfood"
              onChange={() => setSwitched1(!switched1)}
              switched={switched1}
            />
          </Flex>

          <Flex alignItems="center">
            <Flex.Item flex="grow">
              <Label htmlFor="boardoutfits">
                <Flex direction="column" gap={1}>
                  <Text>Outfits</Text>
                  <Text size="100">138 pins · 5 sections</Text>
                </Flex>
              </Label>
            </Flex.Item>
            <Switch
              id="boardoutfits"
              onChange={() => setSwitched2(!switched2)}
              switched={switched2}
            />
          </Flex>

          <Flex alignItems="center">
            <Flex.Item flex="grow">
              <Label htmlFor="boardhomedecor">
                <Flex direction="column" gap={1}>
                  <Text>Home Decor</Text>
                  <Text size="100">33 pins · 2 sections</Text>
                </Flex>
              </Label>
            </Flex.Item>
            <Switch
              id="boardhomedecor"
              onChange={() => setSwitched3(!switched3)}
              switched={switched3}
            />
          </Flex>
        </Flex>
      </Flex>
    </Flex>
  );
}

Disabled and switched combinations

import { Flex, Label, Switch, Text } from 'gestalt';

export default function SwitchExample() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Flex alignItems="center" gap={8}>
        <Flex direction="column" gap={2}>
          <Label htmlFor="base">
            <Text>Base state</Text>
          </Label>
          <Switch id="base" onChange={() => {}} switched={false} />
        </Flex>
        <Flex direction="column" gap={{ column: 2, row: 0 }}>
          <Label htmlFor="switched">
            <Text>Switched</Text>
          </Label>
          <Switch id="switched" onChange={() => {}} switched />
        </Flex>
        <Flex direction="column" gap={{ column: 2, row: 0 }}>
          <Label htmlFor="disabled">
            <Text>Disabled, not switched</Text>
          </Label>
          <Switch disabled id="disabled" onChange={() => {}} switched={false} />
        </Flex>
        <Flex direction="column" gap={{ column: 2, row: 0 }}>
          <Label htmlFor="disabledAndSwitched">
            <Text>Disabled and switched</Text>
          </Label>
          <Switch
            disabled
            id="disabledAndSwitched"
            onChange={() => {}}
            switched
          />
        </Flex>
      </Flex>
    </Flex>
  );
}

Writing

Do
  • Be clear and brief with Switch labels so they can be easily understood.
  • When possible, use verbs to clarify the action. Something like “set…” or “show…”.
  • If possible, be clear whether the setting is activated or deactivated.
  • Use sentence case for labels.
Don't
  • Use vague language out of context, like “turn on” or “turn off” repeating the state of the switch is redundant and can clutter the interface.
  • Don’t use “you,” “your,” or “my” to describe an action. Instead describe switches objectively.

Component quality checklist

Component quality checklist
Quality item
Status
Status description
Figma Library
Ready
Component is available in Figma for web and mobile web.
Responsive Web
Ready
Component responds to changing viewport sizes in web and mobile web.

RadioGroup
Use when presenting a user with a list of choices for which there can only be one selection.

Checkbox
Used when presenting a user with a list of choices for which there can be multiple selections.

Fieldset
Used to group a list of related Switches with a legend that describes the list.

Edit page on GitHub