0
# @react-aria/button
1

2
@react-aria/button provides React hooks for implementing accessible button components with comprehensive keyboard, mouse, and touch interaction handling. It offers the useButton hook that enables developers to create ARIA-compliant button interfaces across various HTML elements while maintaining consistent focus management, press state handling, and accessibility attributes.
3

4
## Package Information
5

6
- **Package Name**: @react-aria/button
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @react-aria/button`
10

11
## Core Imports
12

13
```typescript
14
import { useButton, useToggleButton, useToggleButtonGroup, useToggleButtonGroupItem } from "@react-aria/button";
15
import { useToggleState } from "@react-stately/toggle";
16
import { useToggleGroupState } from "@react-stately/toggle";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { useButton, useToggleButton, useToggleButtonGroup, useToggleButtonGroupItem } = require("@react-aria/button");
23
const { useToggleState, useToggleGroupState } = require("@react-stately/toggle");
24
```
25

26
## Basic Usage
27

28
```typescript
29
import { useButton, useToggleButton, useToggleButtonGroup, useToggleButtonGroupItem } from "@react-aria/button";
30
import { useToggleState, useToggleGroupState } from "@react-stately/toggle";
31
import { useRef } from "react";
32

33
// Basic button
34
function Button(props) {
35
  let ref = useRef<HTMLButtonElement | null>(null);
36
  let { buttonProps, isPressed } = useButton(props, ref);
37

38
  return (
39
    <button {...buttonProps} ref={ref}>
40
      {props.children}
41
    </button>
42
  );
43
}
44

45
// Toggle button
46
function ToggleButton(props) {
47
  let ref = useRef<HTMLButtonElement | null>(null);
48
  let state = useToggleState(props);
49
  let { buttonProps, isPressed, isSelected } = useToggleButton(props, state, ref);
50

51
  return (
52
    <button {...buttonProps} ref={ref} style={{ background: isSelected ? 'blue' : 'gray' }}>
53
      {props.children}
54
    </button>
55
  );
56
}
57

58
// Toggle button group
59
function ToggleButtonGroup(props) {
60
  let groupRef = useRef<HTMLDivElement | null>(null);
61
  let state = useToggleGroupState(props);
62
  let { groupProps } = useToggleButtonGroup(props, state, groupRef);
63

64
  return (
65
    <div {...groupProps} ref={groupRef}>
66
      {props.children}
67
    </div>
68
  );
69
}
70

71
// Toggle button group item
72
function ToggleButtonGroupItem(props) {
73
  let ref = useRef<HTMLButtonElement | null>(null);
74
  let { buttonProps, isPressed, isSelected } = useToggleButtonGroupItem(props, props.state, ref);
75

76
  return (
77
    <button {...buttonProps} ref={ref} style={{ background: isSelected ? 'blue' : 'gray' }}>
78
      {props.children}
79
    </button>
80
  );
81
}
82

83
// Usage examples
84
<Button onPress={() => alert('Button pressed!')}>Click me</Button>
85
<ToggleButton>Toggle me</ToggleButton>
86
```
87

88
## Architecture
89

90
@react-aria/button is built around several key components:
91

92
- **Core Button Hook**: `useButton` provides fundamental button behavior and accessibility
93
- **Toggle Extensions**: `useToggleButton` extends button behavior with selection state management  
94
- **Group Management**: `useToggleButtonGroup` and `useToggleButtonGroupItem` handle collections of toggle buttons
95
- **Element Flexibility**: All hooks support multiple HTML element types (button, a, div, input, span)
96
- **ARIA Compliance**: Automatic ARIA role and attribute management for accessibility
97
- **Press State Management**: Consistent press state handling across interaction methods
98

99
## Capabilities
100

101
### Core Button Functionality
102

103
Provides fundamental button behavior with accessibility, press state management, and support for multiple element types.
104

105
```typescript { .api }
106
function useButton<E extends ElementType>(
107
  props: AriaButtonOptions<E>, 
108
  ref: RefObject<Element | null>
109
): ButtonAria<DOMAttributes>;
110

111
interface AriaButtonOptions<E extends ElementType> extends Omit<AriaButtonProps<E>, 'children'> {}
112

113
interface ButtonAria<T> {
114
  /** Props for the button element. */
115
  buttonProps: T;
116
  /** Whether the button is currently pressed. */
117
  isPressed: boolean;
118
}
119
```
120

121
[Core Button Functionality](./core-button.md)
122

123
### Toggle Button Functionality
124

125
Extends button behavior with selection state management for toggle buttons that maintain on/off states.
126

127
```typescript { .api }
128
function useToggleButton<E extends ElementType>(
129
  props: AriaToggleButtonOptions<E>,
130
  state: ToggleState,
131
  ref: RefObject<Element | null>
132
): ToggleButtonAria<DOMAttributes>;
133

134
interface AriaToggleButtonOptions<E extends ElementType> extends Omit<AriaToggleButtonProps<E>, 'children'> {}
135

136
interface ToggleButtonAria<T> extends ButtonAria<T> {
137
  /** Whether the button is selected. */
138
  isSelected: boolean;
139
  /** Whether the button is disabled. */
140
  isDisabled: boolean;
141
}
142
```
143

144
[Toggle Button Functionality](./toggle-button.md)
145

146
### Toggle Button Groups
147

148
Manages collections of toggle buttons with proper ARIA semantics, supporting both single and multiple selection modes.
149

150
```typescript { .api }
151
function useToggleButtonGroup(
152
  props: AriaToggleButtonGroupProps,
153
  state: ToggleGroupState,
154
  ref: RefObject<HTMLElement | null>
155
): ToggleButtonGroupAria;
156

157
function useToggleButtonGroupItem<E extends ElementType>(
158
  props: AriaToggleButtonGroupItemOptions<E>,
159
  state: ToggleGroupState,
160
  ref: RefObject<Element | null>
161
): ToggleButtonAria<DOMAttributes>;
162

163
interface AriaToggleButtonGroupProps extends ToggleGroupProps, AriaLabelingProps {
164
  /** The orientation of the toggle button group. @default 'horizontal' */
165
  orientation?: Orientation;
166
}
167

168
interface AriaToggleButtonGroupItemOptions<E extends ElementType> extends Omit<AriaToggleButtonGroupItemProps<E>, 'children'> {
169
  /** An identifier for the item in the selectedKeys of a ToggleButtonGroup. */
170
  id: Key;
171
}
172

173
interface ToggleButtonGroupAria {
174
  /** Props for the toggle button group container. */
175
  groupProps: DOMAttributes;
176
}
177
```
178

179
[Toggle Button Groups](./toggle-button-groups.md)
180

181
## Common Types
182

183
```typescript { .api }
184
import { ElementType, RefObject, ReactNode, JSXElementConstructor, MouseEvent, AnchorHTMLAttributes, ButtonHTMLAttributes, HTMLAttributes, InputHTMLAttributes } from 'react';
185
import { AriaLabelingProps, DOMAttributes, FocusableDOMProps, PressEvents, FocusableProps, Key, Orientation } from '@react-types/shared';
186
import { ToggleState, ToggleGroupState, ToggleGroupProps } from '@react-stately/toggle';
187

188
type Selection = 'all' | Set<Key>;
189
type SelectionMode = 'none' | 'single' | 'multiple';
190

191
interface PressEvent {
192
  /** The type of press event being fired. */
193
  type: 'pressstart' | 'pressend' | 'pressup' | 'press';
194
  /** The pointer type that triggered the press event. */
195
  pointerType: 'mouse' | 'pen' | 'touch' | 'keyboard' | 'virtual';
196
  /** The target element of the press event. */
197
  target: Element;
198
  /** Whether the shift keyboard modifier was held during the press event. */
199
  shiftKey: boolean;
200
  /** Whether the ctrl keyboard modifier was held during the press event. */
201
  ctrlKey: boolean;
202
  /** Whether the meta keyboard modifier was held during the press event. */
203
  metaKey: boolean;
204
  /** Whether the alt keyboard modifier was held during the press event. */
205
  altKey: boolean;
206
}
207

208
interface AriaButtonProps<T extends ElementType = 'button'> extends ButtonProps, LinkButtonProps<T>, AriaBaseButtonProps {}
209

210
interface ButtonProps extends PressEvents, FocusableProps {
211
  /** Whether the button is disabled. */
212
  isDisabled?: boolean;
213
  /** The content to display in the button. */
214
  children?: ReactNode;
215
}
216

217
interface LinkButtonProps<T extends ElementType = 'button'> extends AriaButtonElementTypeProps<T> {
218
  /** A URL to link to if elementType="a". */
219
  href?: string;
220
  /** The target window for the link. */
221
  target?: string;
222
  /** The relationship between the linked resource and the current page. */
223
  rel?: string;
224
}
225

226
interface AriaButtonElementTypeProps<T extends ElementType = 'button'> {
227
  /** The HTML element or React element used to render the button. @default 'button' */
228
  elementType?: T | JSXElementConstructor<any>;
229
}
230

231
interface AriaBaseButtonProps extends FocusableDOMProps, AriaLabelingProps {
232
  /** Indicates whether the element is disabled to users of assistive technology. */
233
  'aria-disabled'?: boolean | 'true' | 'false';
234
  /** Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed. */
235
  'aria-expanded'?: boolean | 'true' | 'false';
236
  /** Indicates the availability and type of interactive popup element. */
237
  'aria-haspopup'?: boolean | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog' | 'true' | 'false';
238
  /** Identifies the element (or elements) whose contents or presence are controlled by the current element. */
239
  'aria-controls'?: string;
240
  /** Indicates the current "pressed" state of toggle buttons. */
241
  'aria-pressed'?: boolean | 'true' | 'false' | 'mixed';
242
  /** Indicates whether this element represents the current item within a container or set of related elements. */
243
  'aria-current'?: boolean | 'true' | 'false' | 'page' | 'step' | 'location' | 'date' | 'time';
244
  /** The behavior of the button when used in an HTML form. @default 'button' */
245
  type?: 'button' | 'submit' | 'reset';
246
  /** Whether to prevent focus from moving to the button when pressing it. */
247
  preventFocusOnPress?: boolean;
248
  /** The `<form>` element to associate the button with. */
249
  form?: string;
250
  /** The URL that processes the information submitted by the button. */
251
  formAction?: string;
252
  /** Indicates how to encode the form data that is submitted. */
253
  formEncType?: string;
254
  /** Indicates the HTTP method used to submit the form. */
255
  formMethod?: string;
256
  /** Indicates that the form is not to be validated when it is submitted. */
257
  formNoValidate?: boolean;
258
  /** Overrides the target attribute of the button's form owner. */
259
  formTarget?: string;
260
  /** Submitted as a pair with the button's value as part of the form data. */
261
  name?: string;
262
  /** The value associated with the button's name when it's submitted with the form data. */
263
  value?: string;
264
}
265

266
interface AriaToggleButtonProps<T extends ElementType = 'button'> extends ToggleButtonProps, Omit<AriaBaseButtonProps, 'aria-current' | 'form' | 'formAction' | 'formEncType' | 'formMethod' | 'formNoValidate' | 'formTarget' | 'name' | 'value' | 'type'>, AriaButtonElementTypeProps<T> {}
267

268
interface ToggleButtonProps extends ButtonProps {
269
  /** Whether the element should be selected (controlled). */
270
  isSelected?: boolean;
271
  /** Whether the element should be selected (uncontrolled). */
272
  defaultSelected?: boolean;
273
  /** Handler that is called when the element's selection state changes. */
274
  onChange?: (isSelected: boolean) => void;
275
}
276

277
// Exported Type Aliases
278
type AriaButtonOptions<E extends ElementType> = Omit<AriaButtonProps<E>, 'children'>;
279
type AriaToggleButtonOptions<E extends ElementType> = Omit<AriaToggleButtonProps<E>, 'children'>;
280
type AriaToggleButtonGroupItemProps<E extends ElementType = 'button'> = Omit<AriaToggleButtonProps<E>, 'id' | 'isSelected' | 'defaultSelected' | 'onChange'> & {
281
  /** An identifier for the item in the selectedKeys of a ToggleButtonGroup. */
282
  id: Key;
283
};
284

285
// Return Interfaces
286
interface ButtonAria<T> {
287
  /** Props for the button element. */
288
  buttonProps: T;
289
  /** Whether the button is currently pressed. */
290
  isPressed: boolean;
291
}
292

293
interface ToggleButtonAria<T> extends ButtonAria<T> {
294
  /** Whether the button is selected. */
295
  isSelected: boolean;
296
  /** Whether the button is disabled. */
297
  isDisabled: boolean;
298
}
299

300
interface ToggleButtonGroupAria {
301
  /** Props for the toggle button group container. */
302
  groupProps: DOMAttributes;
303
}
304

305
// State Management Interfaces
306
interface ToggleState {
307
  /** Whether the toggle is selected. */
308
  isSelected: boolean;
309
  /** Sets whether the toggle is selected. */
310
  setSelected(isSelected: boolean): void;
311
  /** Toggles the selection state. */
312
  toggle(): void;
313
}
314

315
interface ToggleGroupState {
316
  /** The keys for the currently selected items. */
317
  selectedKeys: Set<Key>;
318
  /** Whether the collection allows empty selection. */
319
  disallowEmptySelection: boolean;
320
  /** The selection mode for the collection. */
321
  selectionMode: SelectionMode;
322
  /** Whether the collection is disabled. */
323
  isDisabled: boolean;
324
  /** Sets the selected keys. */
325
  setSelected(key: Key, selected: boolean): void;
326
  /** Toggles the selection state of an item. */
327
  toggleKey(key: Key): void;
328
  /** Replaces the selection with only the given key. */
329
  selectKey(key: Key): void;
330
  /** Selects all items in the collection. */
331
  selectAll(): void;
332
  /** Clears the selection. */
333
  clearSelection(): void;
334
}
335

336
interface ToggleGroupProps {
337
  /** The currently selected keys in the collection (controlled). */
338
  selectedKeys?: 'all' | Iterable<Key>;
339
  /** The initial selected keys in the collection (uncontrolled). */
340
  defaultSelectedKeys?: 'all' | Iterable<Key>;
341
  /** Handler that is called when the selection changes. */
342
  onChange?: (keys: Selection) => void;
343
  /** The type of selection that is allowed in the collection. */
344
  selectionMode?: SelectionMode;
345
  /** Whether the collection allows empty selection. */
346
  disallowEmptySelection?: boolean;
347
}
348
```