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.

install	`yarn add @react-aria/button`
version	3.3.1
usage	`import {useToggleButton} from '@react-aria/button'`

View ARIA spec

W3C

API#

useToggleButton(
  props: AriaToggleButtonProps<ElementType>,
  state: ToggleState,
  ref: RefObject<any>
): ButtonAria<HTMLAttributes<any>>

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:

Name	Type	Description
`buttonProps`	`T`	Props for the button element.
`isPressed`	`boolean`	Whether the button is currently pressed.

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/toggle';

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
            ? 'darkblue'
            : 'darkgreen'
          : state.isSelected
          ? 'blue'
          : 'green',
        color: 'white',
        padding: 10,
        cursor: 'pointer',
        userSelect: 'none',
        WebkitUserSelect: 'none',
        border: 'none'
      }}
      ref={ref}>
      {props.children}
    </button>
  );
}

<ToggleButton>Test</ToggleButton>

import {useToggleState} from '@react-stately/toggle';

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
            ? 'darkblue'
            : 'darkgreen'
          : state.isSelected
          ? 'blue'
          : 'green',
        color: 'white',
        padding: 10,
        cursor: 'pointer',
        userSelect: 'none',
        WebkitUserSelect: 'none',
        border: 'none'
      }}
      ref={ref}>
      {props.children}
    </button>
  );
}

<ToggleButton>Test</ToggleButton>

import {useToggleState} from '@react-stately/toggle';

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
            ? 'darkblue'
            : 'darkgreen'
          : state.isSelected
          ? 'blue'
          : 'green',
        color: 'white',
        padding: 10,
        cursor:
          'pointer',
        userSelect:
          'none',
        WebkitUserSelect:
          'none',
        border: 'none'
      }}
      ref={ref}>
      {props.children}
    </button>
  );
}

<ToggleButton>
  Test
</ToggleButton>

Name	Type	Default	Description
`isSelected`	`boolean`	—	Whether the element should be selected (controlled).
`defaultSelected`	`boolean`	—	Whether the element should be selected (uncontrolled).
`onChange`	`( (isSelected: boolean )) => void`	—	Handler that is called when the element's selection state changes.
`isDisabled`	`boolean`	—	Whether the button is disabled.
`children`	`ReactNode`	—	The content to display in the button.
`onPress`	`( (e: PressEvent )) => void`	—	Handler that is called when the press is released over the target.
`onPressStart`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction starts.
`onPressEnd`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
`onPressChange`	`( (isPressed: boolean )) => void`	—	Handler that is called when the press state changes.
`onPressUp`	`( (e: PressEvent )) => void`	—	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`aria-expanded`	`boolean`	—	Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
`aria-haspopup`	`boolean \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog'`	—	Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
`aria-controls`	`string`	—	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`aria-pressed`	`boolean`	—	Indicates the current "pressed" state of toggle buttons.
`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	The behavior of the button when used in an HTML form.
`excludeFromTabOrder`	`boolean`	—	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`elementType`	`T \| JSXElementConstructor<any>`	`'button'`	The HTML element or React element used to render the button, e.g. 'div', 'a', or `RouterLink`.

Name	Type	Description
`type`	`'pressstart' \| 'pressend' \| 'pressup' \| 'press'`	The type of press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`HTMLElement`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.

'mouse'
  | 'pen'
  | 'touch'
  | 'keyboard'
  | 'virtual'

BaseEvent<ReactKeyboardEvent<any>>

T & {stopPropagation: () => void,
continuePropagation: () => void
}

Properties

Name	Type	Description
`isSelected`	`boolean`	Whether the toggle is selected.

Methods

Method	Description
`setSelected( (isSelected: boolean )): void`	Updates selection state.
`toggle(): void`	Toggle the selection state.

Name	Type	Description
`buttonProps`	`T`	Props for the button element.
`isPressed`	`boolean`	Whether the button is currently pressed.

Provides state management for toggle components like checkboxes and switches.

useToggleState(
  (props: ToggleProps
)): ToggleState

Name	Type	Description
`children`	`ReactNode`	The label for the element.
`defaultSelected`	`boolean`	Whether the element should be selected (uncontrolled).
`isSelected`	`boolean`	Whether the element should be selected (controlled).
`onChange`	`( (isSelected: boolean )) => void`	Handler that is called when the element's selection state changes.
`value`	`string`	The value of the input element, used when submitting an HTML form. See MDN.
`name`	`string`	The name of the input element, used when submitting an HTML form. See MDN.
`isDisabled`	`boolean`	Whether the input is disabled.
`isReadOnly`	`boolean`	Whether the input can be selected but not changed by the user.
`validationState`	`ValidationState`	Whether the input should display its "valid" or "invalid" visual styling.
`isRequired`	`boolean`	Whether user input is required on the input before form submission. Often paired with the `necessityIndicator` prop to add a visual indicator to the input.
`autoFocus`	`boolean`	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent )) => void`	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent )) => void`	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	Handler that is called when a key is released.

'valid' | 'invalid'