ButtonToggle

ButtonToggle is a larger alternative to selection components such as Checkbox, RadioButton, and Switch. It enables users to choose between two states - selected or unselected.

also known as Toggle, Action Button, Toggle Switch

Figma:

Ready

Responsive:

N/A

Adaptive:

N/A

A11y:

N/A

Props

Component props
Name	Type	Default
`selected` Required	`boolean`	-
	Toggles between selected/unselected.
`text` Required	`string`	-
	Text to render inside the ButtonToggle to convey the function and purpose of the ButtonToggle.
`accessibilityControls`	`string`	-
	Specifies the `id` of an associated element (or elements) whose contents or visibility are controlled by ButtonToggle so that screen reader users can identify the relationship between elements. See the Accessibility guidelines for details on proper usage.
`accessibilityLabel`	`string`	-
	Label for screen readers to announce ButtonToggle. See the Accessibility guidelines for details on proper usage.
`color`	`"red" \| "transparent"`	`"transparent"`
	The background color of ButtonToggle.
`dataTestId`	`string`	-
	Available for testing purposes, if needed. Consider better queries before using this prop.
`disabled`	`boolean`	`false`
	Indicates if ButtonToggle is disabled. Disabled ButtonToggles are inactive and cannot be interacted with. See the state variant for details on proper usage.
`iconStart`	`unknown`	-
	An icon displayed before the text to help clarify the usage of ButtonToggle.
`onBlur`	`(arg1: { event: React.FocusEvent<HTMLButtonElement> }) => void`	-
	Callback invoked when ButtonToggle loses focus.
`onClick`	`(arg1: { event: React.MouseEvent<HTMLButtonElement> \| React.KeyboardEvent<HTMLButtonElement>; }) => void`	-
	Callback invoked when the user clicks (press and release) on ButtonToggle with the mouse or keyboard.
`onFocus`	`(arg1: { event: React.FocusEvent<HTMLButtonElement> }) => void`	-
	Callback invoked when ButtonToggle gains focus.
`size`	`"sm" \| "md" \| "lg"`	`"md"`
	sm: 32px, md: 40px, lg: 48px See the size variant variant to learn more.

Usage guidelines

When to use

The ButtonToggle should be used when you require a binary component with distinct on/off states
To demonstrate that items are actively selected for filtering

When not to use

Avoid using the ButtonToggle when a simpler Checkbox, RadioButton, or Switch can be used instead.
Do not use ButtonToggle in replacement of a Button, it should only be used for selected and unselected functionality

Best practices

To make it clearer, you may want to change the label text to indicate that the ButtonToggle has been selected. For instance, changing "Follow" to "Following."

Make sure that the ButtonToggle(s) in your application are consistently styled and placed. This should also apply to their sizing, maintaining uniformity throughout the experience.

Place the ButtonToggle(s) in a location where users would naturally expect to find them, taking into consideration the context. For instance, position it next to a related feature.

If the ButtonToggle(s) trigger a significant action or irreversible change, it is recommended to include a confirmation, such as a ModalAlert message.

Accessibility

Not available

ARIA attributes

When ButtonToggle text does not provide sufficient context about the ButtonToggle’s behavior, supply a short, descriptive label for screen-readers using accessibilityLabel.
Texts like “Best“, “Views“, or “Save“ can be confusing when a screen reader reads them out of context. In those cases, we must pass an alternative text with deeper context to replace the ButtonToggle text, like “Follow Ryan” or “Shop Wedding Invitations”.

If ButtonToggle is used as a control button to show/hide a Popover-based component, we recommend passing the following ARIA attributes to assist screen readers:

accessibilityLabel: if present, read by screen readers read instead of the text prop. It populates aria-label.
accessibilityControls: informs the screen reader that ButtonToggle controls the display of an interactive widget or element, or is used to modify another component. It can be used to associate the corresponding element with the ButtonToggle. It populates aria-controls.

Color contrast in disabled state

Disabled ButtonToggles do not need to pass color contrast guidelines.

From w3.org, 1.4.3 Contrast (Minimum): Text or images of text that are part of an inactive user interface component, that are pure decoration, that are not visible to anyone, or that are part of a picture that contains significant other visual content, have no contrast requirement.

Our current disabled ButtonToggle implementation does fail to pass color contrast on accessibility integration tests. To exclude disabled buttontoggles from the integration tests we recomment conditionally setting a data-test-id={ isDisabled ? "disabled-button-<name>" : undefined } and excluding them from the integration test.

On cypress-axe that can be achieved with cy.a11yCheck({ exclude: [['[data-test-id="disabled-button-submit"]']] })

`Localization`

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


Avoid truncating ButtonToggle text whenever possible. Refer to the 
              ButtonToggle usage guidelines for more information

import { useState } from 'react';
import { ButtonToggle, Flex } from 'gestalt';

export default function Example() {
  const [selected, setSelected] = useState(false);

  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <ButtonToggle
        iconStart="sparkle"
        onClick={() => setSelected(!selected)}
        selected={selected}
        size="lg"
        text={selected ? 'Gefolgt' : 'Folgen'}
      />
    </Flex>
  );
}

`Variants`

`Size`

ButtonToggle is available in 3 fixed sizes. The ButtonToggle text has always a fixed size of 16px:



lg (48px)
 Large is the only size that should be used on Pinner surfaces.
md (40px)
 Medium is used on more dense UI such as business surfaces or internal tools.
sm (32px)
 Small should be used sparingly and only in places where the UI is very dense.

size="sm"

size="md"

size="lg"

`Color`


Red (Primary)
 High emphasis, used for the Save action.
Transparent
 Low emphasis when placed on dark/image backgrounds, used for actions in that context.

import { Box, ButtonToggle, Flex, Text } from 'gestalt';

export default function Example() {
  return (
    <Box padding={4}>
      <Flex gap={6} height="100%" width="100%" wrap>
        <Flex direction="column" gap={2}>
          <ButtonToggle color="red" selected={false} size="lg" text="Save" />
          <Text size="200" weight="bold">
            color=&quot;red&quot;
          </Text>
        </Flex>
        <Flex direction="column" gap={2}>
          <ButtonToggle
            color="transparent"
            selected={false}
            size="lg"
            text="Follow"
          />
          <Text size="200" weight="bold">
            color=&quot;transparent&quot;
          </Text>
        </Flex>
      </Flex>
    </Box>
  );
}

`Icons`

iconStart adds an icon before the ButtonToggle text.

import { ButtonToggle, Flex } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <ButtonToggle
        accessibilityLabel="Default"
        iconStart="sparkle"
        selected={false}
        size="lg"
        text="Default"
      />
    </Flex>
  );
}

`States`


Default
 The initial state of a ButtonToggle that represents it is in a non-selected state.
Disabled
Used to block user interaction such as hover, focus and click. Disabled ButtonToggles are completely unreachable by a keyboard and screenreader, so do not attach Tooltips to disabled ButtonToggles.
Selected
  When ButtonToggle is currently active or selected.

import { ButtonToggle, Flex } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <ButtonToggle
        accessibilityLabel="Save"
        color="red"
        selected={false}
        size="lg"
        text="Save"
      />
    </Flex>
  );
}

import { ButtonToggle, Flex } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <ButtonToggle
        accessibilityLabel="Save"
        color="red"
        selected={false}
        size="lg"
        text="Save"
      />
      <ButtonToggle
        accessibilityLabel="Follow"
        disabled
        selected={false}
        size="lg"
        text="Follow"
      />
    </Flex>
  );
}

import { ButtonToggle, Flex } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <ButtonToggle
        accessibilityLabel="Saved"
        color="red"
        selected
        size="lg"
        text="Save"
      />
      <ButtonToggle
        accessibilityLabel="Following"
        selected
        size="lg"
        text="Following"
      />
    </Flex>
  );
}

`Writing`

Do


Use fewer than three words, ideally only one.
Use clear and concise copy for labels, tooltips, and any supporting text.
To make it clearer, you may want to change the label text to indicate that the ButtonToggle has been selected. For instance, changing "follow" to "Following."
Make sure that all text is easy to translate for localization purposes.

Don't


Do not use punctuation.

`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		Component does not respond 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.

              Switch
Use for single-cell options that can be turned on or off. Examples include a list of settings that take effect immediately without having to confirm Form submission.

              TagData
TagData enables people to select multiple categories to compare with each other in a graph or chart.

              TileData
TileData enables users to select multiple categories to compare with each other in a graph or chart view, while still being able to see all of the data points.

Edit page on GitHub

ButtonToggle

also known as Toggle, Action Button, Toggle Switch

Props

Usage guidelines

Best practices

Accessibility

ARIA attributes

Color contrast in disabled state

Localization

Variants

Size

Color

Icons

States

Writing

Component quality checklist

Related