ToggleButton

ToggleButtons allow users to toggle a selection on or off, for example switching between two states or modes.

Example#

<ToggleButton>Pin</ToggleButton>

<ToggleButton>Pin</ToggleButton>

<ToggleButton>
  Pin
</ToggleButton>

Content#

ToggleButtons can have a label, an icon, or both. An icon is provided by passing an icon component as a child to the ToggleButton. A visible label can be provided by passing a string or a Text component as a child, depending on whether the ToggleButton has an accompanying icon.

import {Text} from '@adobe/react-spectrum';
import Pin from '@spectrum-icons/workflow/PinOff';

<ToggleButton>
  <Pin />
  <Text>Icon + Label</Text>
</ToggleButton>

import {Text} from '@adobe/react-spectrum';
import Pin from '@spectrum-icons/workflow/PinOff';

<ToggleButton>
  <Pin />
  <Text>Icon + Label</Text>
</ToggleButton>

import {Text} from '@adobe/react-spectrum';
import Pin from '@spectrum-icons/workflow/PinOff';

<ToggleButton>
  <Pin />
  <Text>
    Icon + Label
  </Text>
</ToggleButton>

Accessibility#

If no visible label is provided (e.g. an icon only button), an alternative text label must be provided to identify the control for accessibility. This should be added using the aria-label prop.

<ToggleButton aria-label="Icon only">
  <Pin />
</ToggleButton>

<ToggleButton aria-label="Icon only">
  <Pin />
</ToggleButton>

<ToggleButton aria-label="Icon only">
  <Pin />
</ToggleButton>

Note: ToggleButton should not be used when the content of the button changes between selection states, for example, mute/unmute or play/pause. In these cases, use an ActionButton instead.

Internationalization#

In order to internationalize an ToggleButton, a localized string should be passed to the children or aria-label prop.

Value#

ToggleButtons are not selected by default. The defaultSelected prop can be used to set the default state (uncontrolled). Alternatively, the isSelected prop can be used to make the selected state controlled. See React's documentation on uncontrolled components for more info, and Events, below, for an example of controlled behavior.

Events#

ToggleButtons support user interactions via mouse, keyboard, and touch. When pressing the button, the selection state is toggled, and the onChange event is fired. The following example uses an onChange handler to update React state.

function Example() {
  let [isSelected, setSelected] = React.useState(false);

  return (
    <ToggleButton
      isEmphasized
      isSelected={isSelected}
      onChange={setSelected}
      aria-label="Pin">
      <Pin />
    </ToggleButton>
  );
}

function Example() {
  let [isSelected, setSelected] = React.useState(false);

  return (
    <ToggleButton
      isEmphasized
      isSelected={isSelected}
      onChange={setSelected}
      aria-label="Pin">
      <Pin />
    </ToggleButton>
  );
}

function Example() {
  let [
    isSelected,
    setSelected
  ] = React.useState(
    false
  );

  return (
    <ToggleButton
      isEmphasized
      isSelected={isSelected}
      onChange={setSelected}
      aria-label="Pin"
    >
      <Pin />
    </ToggleButton>
  );
}

Props#

Visual options#

Quiet#

View guidelines

<ToggleButton isQuiet>Pin</ToggleButton>

<ToggleButton isQuiet>Pin</ToggleButton>

<ToggleButton isQuiet>
  Pin
</ToggleButton>

Disabled#

View guidelines

<ToggleButton isDisabled>Pin</ToggleButton>

<ToggleButton isDisabled>Pin</ToggleButton>

<ToggleButton
  isDisabled
>
  Pin
</ToggleButton>

Emphasized#

View guidelines

<ToggleButton isEmphasized defaultSelected>Pin</ToggleButton>

<ToggleButton isEmphasized defaultSelected>
  Pin
</ToggleButton>

<ToggleButton
  isEmphasized
  defaultSelected
>
  Pin
</ToggleButton>

Static color#

The staticColor prop can be used when a ToggleButton is displayed over a color background. When selected, the icon and text automatically take on the color of the background. You are responsible for choosing the static color variant that ensures the text meets an accessible contrast ratio with the background.

<Flex wrap gap="size-250">
  <View backgroundColor="static-blue-700" padding="size-500">
    <ToggleButton staticColor="white">
      <Pin />
      <Text>Pin</Text>
    </ToggleButton>
  </View>
  <View backgroundColor="static-yellow-400" padding="size-500">
    <ToggleButton staticColor="black" isQuiet defaultSelected>
      <Pin />
      <Text>Pin</Text>
    </ToggleButton>
  </View>
</Flex>

<Flex wrap gap="size-250">
  <View
    backgroundColor="static-blue-700"
    padding="size-500"
  >
    <ToggleButton staticColor="white">
      <Pin />
      <Text>Pin</Text>
    </ToggleButton>
  </View>
  <View
    backgroundColor="static-yellow-400"
    padding="size-500"
  >
    <ToggleButton
      staticColor="black"
      isQuiet
      defaultSelected
    >
      <Pin />
      <Text>Pin</Text>
    </ToggleButton>
  </View>
</Flex>

<Flex
  wrap
  gap="size-250"
>
  <View
    backgroundColor="static-blue-700"
    padding="size-500"
  >
    <ToggleButton staticColor="white">
      <Pin />
      <Text>Pin</Text>
    </ToggleButton>
  </View>
  <View
    backgroundColor="static-yellow-400"
    padding="size-500"
  >
    <ToggleButton
      staticColor="black"
      isQuiet
      defaultSelected
    >
      <Pin />
      <Text>Pin</Text>
    </ToggleButton>
  </View>
</Flex>