Switch

View source 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).

Props

Component props
Name	Type	Default
`id` Required	`string`	-
	A unique identifier for the element.
`onChange` Required	`({\| event: SyntheticInputEvent<>, 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 RadioButtons instead.

Best practices

Use a label to give Switch context when possible.

Don't

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

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.

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 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.

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

      return (
        <Flex direction="column" gap={2} width="100%" maxWidth={300}>
            <Heading size="300">Tune your home feed</Heading>
            <Text>Turn off any boards that you don'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
                  switched={switched1}
                  onChange={() => setSwitched1(!switched1)}
                  id="boardfood"
                />
              </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
                  switched={switched2}
                  onChange={() => setSwitched2(!switched2)}
                  id="boardoutfits"
                />
              </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
                  onChange={() => setSwitched3(!switched3)}
                  id="boardhomedecor"
                  switched={switched3}
                />
              </Flex>
            </Flex>
          </Flex>
        );
      }

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

      return (
        <Flex direction="column" gap={2} width="100%" maxWidth={300}>
            <Heading size="300">Tune your home feed</Heading>
            <Text>Turn off any boards that you don'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
                  switched={switched1}
                  onChange={() => setSwitched1(!switched1)}
                  id="boardfood"
                />
              </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
                  switched={switched2}
                  onChange={() => setSwitched2(!switched2)}
                  id="boardoutfits"
                />
              </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
                  onChange={() => setSwitched3(!switched3)}
                  id="boardhomedecor"
                  switched={switched3}
                />
              </Flex>
            </Flex>
          </Flex>
        );
      }

Disabled and switched combinations

function SwitchExample() {
  return (
    <Flex alignItems="center" gap={8}>
      <Flex direction="column" gap={2}>
        <Label htmlFor="base">
          <Text>Base state</Text>
        </Label>
        <Switch
          onChange={() => {}}
          id="base"
          switched={false}
        />
      </Flex>
      <Flex direction="column" gap={2}>
      <Label htmlFor="switched">
        <Text>Switched</Text>
      </Label>
      <Switch
        onChange={() => {}}
        id="switched"
        switched={true}
      />
    </Flex>
    <Flex direction="column" gap={2}>
        <Label htmlFor="disabled">
          <Text>Disabled, not switched</Text>
        </Label>
        <Switch
          onChange={() => {}}
          id="disabled"
          switched={false}
          disabled={true}
        />
      </Flex>
      <Flex direction="column" gap={2}>
        <Label htmlFor="disabledAndSwitched">
          <Text>Disabled and switched</Text>
        </Label>
        <Switch
          onChange={() => {}}
          id="disabledAndSwitched"
          switched={true}
          disabled={true}
        />
      </Flex>
    </Flex>
  );
}

function SwitchExample() {
  return (
    <Flex alignItems="center" gap={8}>
      <Flex direction="column" gap={2}>
        <Label htmlFor="base">
          <Text>Base state</Text>
        </Label>
        <Switch
          onChange={() => {}}
          id="base"
          switched={false}
        />
      </Flex>
      <Flex direction="column" gap={2}>
      <Label htmlFor="switched">
        <Text>Switched</Text>
      </Label>
      <Switch
        onChange={() => {}}
        id="switched"
        switched={true}
      />
    </Flex>
    <Flex direction="column" gap={2}>
        <Label htmlFor="disabled">
          <Text>Disabled, not switched</Text>
        </Label>
        <Switch
          onChange={() => {}}
          id="disabled"
          switched={false}
          disabled={true}
        />
      </Flex>
      <Flex direction="column" gap={2}>
        <Label htmlFor="disabledAndSwitched">
          <Text>Disabled and switched</Text>
        </Label>
        <Switch
          onChange={() => {}}
          id="disabledAndSwitched"
          switched={true}
          disabled={true}
        />
      </Flex>
    </Flex>
  );
}

Writing

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.

RadioButton
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

Switch

Props

Usage guidelines

Best practices

Accessibility

Keyboard navigation

Localization

Variants

With a label

Disabled and switched combinations

Writing

Related