useToggleButton

Provides the behavior and accessibility implementation for a toggle button component. ToggleButtons allow users to toggle a selection on or off, for example switching between two states or modes.

API#

Features#

Toggle buttons are similar to action buttons, but support an additional selection state that is toggled when a user presses the button. There is no built-in HTML element that represents a toggle button, so React Aria implements it using ARIA attributes.

• Native HTML <button>, <a>, and custom element type support
• Exposed as a toggle button via ARIA
• Mouse and touch event handling, and press state management
• Keyboard focus management and cross browser normalization
• Keyboard event support for Space and Enter keys

Anatomy#

Toggle buttons consist of a clickable area usually containing a textual label or an icon that users can click to toggle a selection state. In addition, keyboard users may toggle the state using the Space or Enter keys.

useToggleButton returns props to be spread onto the button element, along with a boolean indicating whether the user is currently pressing the button:

Selection state is managed by the useToggleState hook in @react-stately/toggle. The state object should be passed as an option to useToggleButton.

If a visual label is not provided (e.g. an icon only button), then an aria-label or aria-labelledby prop must be passed to identify the button to assistive technology.

Example#

By default, useToggleButton assumes that you are using it with a native <button> element. You can use a custom element type by passing the elementType prop to useToggleButton. See the useButton docs for an example of this.

The following example shows how to use the useToggleButton and useToggleState hooks to build a toggle button. The toggle state is used to switch between a green and blue background when unselected and selected respectively. In addition, the isPressed state is used to adjust the background to be darker when the user presses down on the button.

import {useToggleState} from 'react-stately';
import {useToggleButton} from 'react-aria';
import {useRef} from 'react';

function ToggleButton(props) {
  let ref = useRef();
  let state = useToggleState(props);
  let { buttonProps, isPressed } = useToggleButton(props, state, ref);

  return (
    <button
      {...buttonProps}
      style={{
        background: isPressed
          ? state.isSelected ? 'darkgreen' : 'gray'
          : state.isSelected
          ? 'green'
          : 'lightgray',
        color: state.isSelected ? 'white' : 'black',
        padding: 10,
        fontSize: 16,
        userSelect: 'none',
        WebkitUserSelect: 'none',
        border: 'none'
      }}
      ref={ref}
    >
      {props.children}
    </button>
  );
}

<ToggleButton>Pin</ToggleButton>

import {useToggleState} from 'react-stately';
import {useToggleButton} from 'react-aria';
import {useRef} from 'react';

function ToggleButton(props) {
  let ref = useRef();
  let state = useToggleState(props);
  let { buttonProps, isPressed } = useToggleButton(
    props,
    state,
    ref
  );

  return (
    <button
      {...buttonProps}
      style={{
        background: isPressed
          ? state.isSelected ? 'darkgreen' : 'gray'
          : state.isSelected
          ? 'green'
          : 'lightgray',
        color: state.isSelected ? 'white' : 'black',
        padding: 10,
        fontSize: 16,
        userSelect: 'none',
        WebkitUserSelect: 'none',
        border: 'none'
      }}
      ref={ref}
    >
      {props.children}
    </button>
  );
}

<ToggleButton>Pin</ToggleButton>

import {useToggleState} from 'react-stately';
import {useToggleButton} from 'react-aria';
import {useRef} from 'react';

function ToggleButton(
  props
) {
  let ref = useRef();
  let state =
    useToggleState(
      props
    );
  let {
    buttonProps,
    isPressed
  } = useToggleButton(
    props,
    state,
    ref
  );

  return (
    <button
      {...buttonProps}
      style={{
        background:
          isPressed
            ? state
                .isSelected
              ? 'darkgreen'
              : 'gray'
            : state
                .isSelected
            ? 'green'
            : 'lightgray',
        color:
          state
              .isSelected
            ? 'white'
            : 'black',
        padding: 10,
        fontSize: 16,
        userSelect:
          'none',
        WebkitUserSelect:
          'none',
        border: 'none'
      }}
      ref={ref}
    >
      {props.children}
    </button>
  );
}

<ToggleButton>
  Pin
</ToggleButton>

Usage#

The following examples show how to use the ToggleButton component created in the above example.

Controlled selection state#

A default selection state for a toggle button can be set using the defaultSelected prop, or controlled with the isSelected prop. The onChange event is fired when the user presses the button, toggling the boolean. See React's documentation on uncontrolled components for more info.

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

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

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

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

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

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

Disabled#

A ToggleButton can be disabled using the isDisabled prop.

<ToggleButton isDisabled>Pin</ToggleButton>

<ToggleButton isDisabled>Pin</ToggleButton>

<ToggleButton
  isDisabled
>
  Pin
</ToggleButton>