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.
install | yarn add react-aria |
---|---|
version | 3.33.1 |
usage | import {useButton} from 'react-aria' |
API#
useButton(
(props: AriaButtonOptions<ElementType>,
, ref: RefObject<any>
)): ButtonAria<HTMLAttributes<any>>
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
Read our blog post about the complexities of building buttons that work well across devices and interaction methods.
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';
import {useRef} from 'react';
function Button(props) {
let ref = useRef<HTMLButtonElement | null>(null);
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';
import {useRef} from 'react';
function Button(props) {
let ref = useRef<HTMLButtonElement | null>(null);
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';
import {useRef} from 'react';
function Button(props) {
let ref = useRef<
| HTMLButtonElement
| null
>(null);
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<HTMLButtonElement | null>(null);
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<HTMLButtonElement | null>(null);
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<
| HTMLButtonElement
| null
>(null);
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>
Usage#
The following examples show how to use the Button
component created in the above example.
Events#
useButton
supports user interactions via mouse, keyboard, and touch. You can handle all of these via the onPress
prop. This is similar to the standard onClick
event, but normalized to support all interaction methods equally. In addition, the onPressStart
, onPressEnd
, and onPressChange
events are fired as the user interacts with the button.
Each of these handlers receives a PressEvent
, which exposes information about the target and the type of event that triggered the interaction. See usePress for more details.
function Example() {
let [pointerType, setPointerType] = React.useState(null);
return (
<>
<Button
onPressStart={(e) => setPointerType(e.pointerType)}
onPressEnd={(e) => setPointerType(null)}
>
Press me
</Button>
<p>
{pointerType
? `You are pressing the button with a
: !`'Ready to be pressed.'}
</p>
</>
);
}
function Example() {
let [pointerType, setPointerType] = React.useState(null);
return (
<>
<Button
onPressStart={(e) => setPointerType(e.pointerType)}
onPressEnd={(e) => setPointerType(null)}
>
Press me
</Button>
<p>
{pointerType
? `You are pressing the button with a
: !`'Ready to be pressed.'}
</p>
</>
);
}
function Example() {
let [
pointerType,
setPointerType
] = React.useState(
null
);
return (
<>
<Button
onPressStart={(e) =>
setPointerType(
e.pointerType
)}
onPressEnd={(e) =>
setPointerType(
null
)}
>
Press me
</Button>
<p>
{pointerType
? `You are pressing the button with a
: !`'Ready to be pressed.'}
</p>
</>
);
}
Disabled#
A Button
can be disabled using the isDisabled
prop.
<Button isDisabled>Pin</Button>
<Button isDisabled>Pin</Button>
<Button isDisabled>
Pin
</Button>