useButton

Provides the behavior and accessibility implementation for a button component. Handles mouse, keyboard, and touch interactions, focus behavior, and ARIA props for both native button elements and custom element types.

API#

Features#

On the surface, building a custom styled button seems simple. However, there are many cross browser inconsistencies in interactions and accessibility features to consider. useButton handles all of these interactions for you, so you can focus on the styling.

• Native HTML <button> support
• <a> and custom element type support 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#

Buttons consist of a clickable area usually containing a textual label or an icon that users can click to perform an action. In addition, keyboard users may activate buttons using the Space or Enter keys.

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, useButton assumes that you are using it with a native <button> element.

import {useButton} from '@react-aria/button';
import {useRef} from 'react';

function Button(props) {
  let ref = useRef();
  let { buttonProps } = useButton(props, ref);
  let { children } = props;

  return (
    <button {...buttonProps} ref={ref}>
      {children}
    </button>
  );
}

<Button onPress={() => alert('Button pressed!')}>Test</Button>

import {useButton} from '@react-aria/button';
import {useRef} from 'react';

function Button(props) {
  let ref = useRef();
  let { buttonProps } = useButton(props, ref);
  let { children } = props;

  return (
    <button {...buttonProps} ref={ref}>
      {children}
    </button>
  );
}

<Button onPress={() => alert('Button pressed!')}>
  Test
</Button>

import {useButton} from '@react-aria/button';
import {useRef} from 'react';

function Button(props) {
  let ref = useRef();
  let { buttonProps } =
    useButton(
      props,
      ref
    );
  let { children } =
    props;

  return (
    <button
      {...buttonProps}
      ref={ref}
    >
      {children}
    </button>
  );
}

<Button
  onPress={() =>
    alert(
      'Button pressed!'
    )}
>
  Test
</Button>

Custom element type#

Sometimes you might need to use an element other than a native <button>. useButton supports this via the elementType prop. When used with an element other than a native button, useButton automatically applies the necessary ARIA roles and attributes to ensure that the element is exposed to assistive technology as a button.

In addition, this example shows usage of the isPressed value returned by useButton to properly style the button's active state. You could use the CSS :active pseudo class for this, but isPressed properly handles when the user drags their pointer off of the button, along with keyboard support and better touch screen support.

function Button(props) {
  let { children } = props;
  let ref = useRef();
  let { buttonProps, isPressed } = useButton({
    ...props,
    elementType: 'span'
  }, ref);

  return (
    <span
      {...buttonProps}
      style={{
        background: isPressed ? 'darkgreen' : 'green',
        color: 'white',
        padding: 10,
        cursor: 'pointer',
        userSelect: 'none',
        WebkitUserSelect: 'none'
      }}
      ref={ref}
    >
      {children}
    </span>
  );
}

<Button onPress={() => alert('Button pressed!')}>Test</Button>

function Button(props) {
  let { children } = props;
  let ref = useRef();
  let { buttonProps, isPressed } = useButton({
    ...props,
    elementType: 'span'
  }, ref);

  return (
    <span
      {...buttonProps}
      style={{
        background: isPressed ? 'darkgreen' : 'green',
        color: 'white',
        padding: 10,
        cursor: 'pointer',
        userSelect: 'none',
        WebkitUserSelect: 'none'
      }}
      ref={ref}
    >
      {children}
    </span>
  );
}

<Button onPress={() => alert('Button pressed!')}>
  Test
</Button>

function Button(props) {
  let { children } =
    props;
  let ref = useRef();
  let {
    buttonProps,
    isPressed
  } = useButton({
    ...props,
    elementType: 'span'
  }, ref);

  return (
    <span
      {...buttonProps}
      style={{
        background:
          isPressed
            ? 'darkgreen'
            : 'green',
        color: 'white',
        padding: 10,
        cursor:
          'pointer',
        userSelect:
          'none',
        WebkitUserSelect:
          'none'
      }}
      ref={ref}
    >
      {children}
    </span>
  );
}

<Button
  onPress={() =>
    alert(
      'Button pressed!'
    )}
>
  Test
</Button>