0
# Core Button Functionality
1

2
Provides fundamental button behavior with accessibility, press state management, and support for multiple element types. The `useButton` hook handles all interactions for button components across different HTML elements while maintaining ARIA compliance.
3

4
## Capabilities
5

6
### useButton Hook
7

8
Creates accessible button behavior for any HTML element with comprehensive interaction handling.
9

10
```typescript { .api }
11
/**
12
 * Provides the behavior and accessibility implementation for a button component. 
13
 * Handles mouse, keyboard, and touch interactions, focus behavior, and ARIA props 
14
 * for both native button elements and custom element types.
15
 * @param props - Props to be applied to the button
16
 * @param ref - A ref to a DOM element for the button
17
 */
18
function useButton(props: AriaButtonOptions<'button'>, ref: RefObject<HTMLButtonElement | null>): ButtonAria<ButtonHTMLAttributes<HTMLButtonElement>>;
19
function useButton(props: AriaButtonOptions<'a'>, ref: RefObject<HTMLAnchorElement | null>): ButtonAria<AnchorHTMLAttributes<HTMLAnchorElement>>;
20
function useButton(props: AriaButtonOptions<'div'>, ref: RefObject<HTMLDivElement | null>): ButtonAria<HTMLAttributes<HTMLDivElement>>;
21
function useButton(props: AriaButtonOptions<'input'>, ref: RefObject<HTMLInputElement | null>): ButtonAria<InputHTMLAttributes<HTMLInputElement>>;
22
function useButton(props: AriaButtonOptions<'span'>, ref: RefObject<HTMLSpanElement | null>): ButtonAria<HTMLAttributes<HTMLSpanElement>>;
23
function useButton(props: AriaButtonOptions<ElementType>, ref: RefObject<Element | null>): ButtonAria<DOMAttributes>;
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import { useButton } from "@react-aria/button";
30
import { useRef } from "react";
31

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

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

44
// Custom element with proper ARIA
45
function CustomButton(props) {
46
  let ref = useRef<HTMLSpanElement | null>(null);
47
  let { buttonProps, isPressed } = useButton({
48
    ...props,
49
    elementType: 'span'
50
  }, ref);
51

52
  return (
53
    <span
54
      {...buttonProps}
55
      style={{
56
        background: isPressed ? 'darkblue' : 'blue',
57
        color: 'white',
58
        padding: 10,
59
        cursor: 'pointer',
60
        userSelect: 'none'
61
      }}
62
      ref={ref}>
63
      {props.children}
64
    </span>
65
  );
66
}
67

68
// Link button
69
function LinkButton(props) {
70
  let ref = useRef<HTMLAnchorElement | null>(null);
71
  let { buttonProps } = useButton({
72
    ...props,
73
    elementType: 'a',
74
    href: props.href
75
  }, ref);
76

77
  return (
78
    <a {...buttonProps} ref={ref}>
79
      {props.children}
80
    </a>
81
  );
82
}
83
```
84

85
### Button Options Interface
86

87
Configuration options for button behavior and appearance.
88

89
```typescript { .api }
90
interface AriaButtonOptions<E extends ElementType> extends Omit<AriaButtonProps<E>, 'children'> {
91
  /** The HTML element or React element used to render the button. @default 'button' */
92
  elementType?: E | JSXElementConstructor<any>;
93
  /** Whether the button is disabled. */
94
  isDisabled?: boolean;
95
  /** Handler that is called when the press is released over the target. */
96
  onPress?: (e: PressEvent) => void;
97
  /** Handler that is called when a press interaction starts. */
98
  onPressStart?: (e: PressEvent) => void;
99
  /** Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target. */
100
  onPressEnd?: (e: PressEvent) => void;
101
  /** Handler that is called when the press state changes. */
102
  onPressChange?: (isPressed: boolean) => void;
103
  /** Handler that is called when a press is released over the target, regardless of whether it started on the target or not. */
104
  onPressUp?: (e: PressEvent) => void;
105
  /** Whether to prevent focus from moving to the button when pressing it. */
106
  preventFocusOnPress?: boolean;
107
  /** Standard onClick handler (called in addition to onPress). */
108
  onClick?: (e: MouseEvent) => void;
109
  /** A URL to link to if elementType="a". */
110
  href?: string;
111
  /** The target window for the link. */
112
  target?: string;
113
  /** The relationship between the linked resource and the current page. */
114
  rel?: string;
115
  /** The behavior of the button when used in an HTML form. @default 'button' */
116
  type?: 'button' | 'submit' | 'reset';
117
  /** The `<form>` element to associate the button with. */
118
  form?: string;
119
  /** The URL that processes the information submitted by the button. */
120
  formAction?: string;
121
  /** Indicates how to encode the form data that is submitted. */
122
  formEncType?: string;
123
  /** Indicates the HTTP method used to submit the form. */
124
  formMethod?: string;
125
  /** Indicates that the form is not to be validated when it is submitted. */
126
  formNoValidate?: boolean;
127
  /** Overrides the target attribute of the button's form owner. */
128
  formTarget?: string;
129
  /** Submitted as a pair with the button's value as part of the form data. */
130
  name?: string;
131
  /** The value associated with the button's name when it's submitted with the form data. */
132
  value?: string;
133
}
134
```
135

136
### Button Return Interface
137

138
Return value from the useButton hook containing props and state.
139

140
```typescript { .api }
141
interface ButtonAria<T> {
142
  /** Props for the button element. */
143
  buttonProps: T;
144
  /** Whether the button is currently pressed. */
145
  isPressed: boolean;
146
}
147
```
148

149
## Element Type Support
150

151
The `useButton` hook supports multiple HTML element types, each with appropriate handling:
152

153
### Native Button Element (`elementType: 'button'`)
154
- Full form integration support
155
- Native disabled attribute
156
- All form-related props (form, formAction, etc.)
157
- Default type="button"
158

159
### Anchor Element (`elementType: 'a'`)
160
- ARIA role="button"
161
- href, target, rel support  
162
- Disabled state via aria-disabled
163
- Keyboard navigation
164

165
### Generic Elements (`elementType: 'div' | 'span'`)
166
- ARIA role="button"
167
- Full keyboard support
168
- Proper focus management
169
- aria-disabled for disabled state
170

171
### Input Element (`elementType: 'input'`)
172
- Native input element behavior
173
- type attribute support
174
- Native disabled attribute
175
- Form integration
176

177
## Accessibility Features
178

179
- **ARIA Compliance**: Automatic role and attribute management
180
- **Keyboard Support**: Space and Enter key handling
181
- **Focus Management**: Proper focus behavior across element types
182
- **Screen Reader Support**: Appropriate labeling and state announcement
183
- **Press State**: Visual press state indication for better UX
184
- **Disabled Handling**: Consistent disabled state across element types
185

186
## Event Handling
187

188
The hook provides normalized event handling across all interaction methods:
189

190
- **Mouse Events**: Click and drag handling
191
- **Touch Events**: Touch start/end/cancel support
192
- **Keyboard Events**: Space and Enter key support
193
- **Focus Events**: Focus and blur management
194
- **Press Events**: Unified press event system
195

196
## Form Integration
197

198
When using with native button elements, full HTML form support is provided:
199

200
- Form association via `form` attribute
201
- Submit/reset button types
202
- Form validation bypass (`formNoValidate`)
203
- Custom form actions and methods
204
- Form data submission with name/value pairs