0
# DOM and ARIA Integration
1

2
Essential DOM properties and ARIA attributes for building accessible web components with comprehensive event handling and element attribute management.
3

4
## Capabilities
5

6
### Basic DOM Properties
7

8
Core DOM properties that can be applied to any component.
9

10
```typescript { .api }
11
/**
12
 * Basic DOM properties available on all components
13
 */
14
interface DOMProps {
15
  /** The element's unique identifier */
16
  id?: string;
17
}
18

19
/**
20
 * DOM properties for focusable elements
21
 */
22
interface FocusableDOMProps extends DOMProps {
23
  /** 
24
   * Whether to exclude the element from the sequential tab order.
25
   * Should be avoided except when alternative keyboard access is available.
26
   */
27
  excludeFromTabOrder?: boolean;
28
}
29
```
30

31
### ARIA Labeling
32

33
ARIA attributes for labeling and describing elements for screen readers.
34

35
```typescript { .api }
36
/**
37
 * ARIA labeling properties for accessibility
38
 */
39
interface AriaLabelingProps {
40
  /** Defines a string value that labels the current element */
41
  "aria-label"?: string;
42
  /** Identifies the element (or elements) that labels the current element */
43
  "aria-labelledby"?: string;
44
  /** Identifies the element (or elements) that describes the object */
45
  "aria-describedby"?: string;
46
  /** Identifies the element (or elements) that provide detailed description */
47
  "aria-details"?: string;
48
}
49

50
/**
51
 * ARIA validation properties
52
 */
53
interface AriaValidationProps {
54
  /** Identifies the element that provides an error message for the object */
55
  "aria-errormessage"?: string;
56
}
57
```
58

59
### Text Input DOM Properties
60

61
Comprehensive DOM properties specifically for text input elements.
62

63
```typescript { .api }
64
/**
65
 * DOM properties for input elements
66
 */
67
interface InputDOMProps {
68
  /** The name of the input element, used when submitting an HTML form */
69
  name?: string;
70
  /** The form element to associate the input with */
71
  form?: string;
72
}
73

74
/**
75
 * Complete DOM properties for text input elements
76
 */
77
interface TextInputDOMProps extends DOMProps, InputDOMProps, TextInputDOMEvents {
78
  /** Describes the type of autocomplete functionality the input should provide */
79
  autoComplete?: string;
80
  /** The maximum number of characters supported by the input */
81
  maxLength?: number;
82
  /** The minimum number of characters required by the input */
83
  minLength?: number;
84
  /** Regex pattern that the value of the input must match to be valid */
85
  pattern?: string;
86
  /** Content that appears in the input when it is empty */
87
  placeholder?: string;
88
  /** The type of input to render */
89
  type?: "text" | "search" | "url" | "tel" | "email" | "password" | (string & {});
90
  /** Hints at the type of data that might be entered by the user */
91
  inputMode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search";
92
  /** Whether to enable autocorrection */
93
  autoCorrect?: string;
94
  /** Whether the element may be checked for spelling errors */
95
  spellCheck?: string;
96
}
97
```
98

99
### Text Input Events
100

101
DOM events specific to text input elements.
102

103
```typescript { .api }
104
/**
105
 * DOM events for text input elements
106
 */
107
interface TextInputDOMEvents {
108
  // Clipboard events
109
  /** Handler that is called when the user copies text */
110
  onCopy?: ClipboardEventHandler<HTMLInputElement>;
111
  /** Handler that is called when the user cuts text */
112
  onCut?: ClipboardEventHandler<HTMLInputElement>;
113
  /** Handler that is called when the user pastes text */
114
  onPaste?: ClipboardEventHandler<HTMLInputElement>;
115

116
  // Composition events
117
  /** Handler that is called when a text composition system starts */
118
  onCompositionStart?: CompositionEventHandler<HTMLInputElement>;
119
  /** Handler that is called when a text composition system completes */
120
  onCompositionEnd?: CompositionEventHandler<HTMLInputElement>;
121
  /** Handler that is called when a new character is received in composition */
122
  onCompositionUpdate?: CompositionEventHandler<HTMLInputElement>;
123

124
  // Selection events
125
  /** Handler that is called when text in the input is selected */
126
  onSelect?: ReactEventHandler<HTMLInputElement>;
127

128
  // Input events
129
  /** Handler that is called when the input value is about to be modified */
130
  onBeforeInput?: FormEventHandler<HTMLInputElement>;
131
  /** Handler that is called when the input value is modified */
132
  onInput?: FormEventHandler<HTMLInputElement>;
133
}
134
```
135

136
### Link Properties
137

138
DOM properties for link elements with router support.
139

140
```typescript { .api }
141
/**
142
 * DOM properties for link elements
143
 */
144
interface LinkDOMProps {
145
  /** A URL to link to */
146
  href?: Href;
147
  /** Hints at the human language of the linked URL */
148
  hrefLang?: string;
149
  /** The target window for the link */
150
  target?: HTMLAttributeAnchorTarget;
151
  /** The relationship between the linked resource and the current page */
152
  rel?: string;
153
  /** Causes the browser to download the linked URL */
154
  download?: boolean | string;
155
  /** A space-separated list of URLs to ping when the link is followed */
156
  ping?: string;
157
  /** How much of the referrer to send when following the link */
158
  referrerPolicy?: HTMLAttributeReferrerPolicy;
159
  /** Options for the configured client side router */
160
  routerOptions?: RouterOptions;
161
}
162

163
// Router configuration types
164
interface RouterConfig {}
165
type Href = RouterConfig extends {href: infer H} ? H : string;
166
type RouterOptions = RouterConfig extends {routerOptions: infer O} ? O : never;
167
```
168

169
### Global DOM Attributes
170

171
Global DOM attributes and events that apply to all elements.
172

173
```typescript { .api }
174
/**
175
 * All DOM attributes supported across both HTML and SVG elements
176
 */
177
interface DOMAttributes<T = FocusableElement> extends AriaAttributes, ReactDOMAttributes<T> {
178
  id?: string | undefined;
179
  role?: AriaRole | undefined;
180
  tabIndex?: number | undefined;
181
  style?: CSSProperties | undefined;
182
  className?: string | undefined;
183
}
184

185
/**
186
 * DOM attributes for group elements
187
 */
188
interface GroupDOMAttributes extends Omit<DOMAttributes<HTMLElement>, "role"> {
189
  role?: "group" | "region" | "presentation";
190
}
191

192
/**
193
 * Global attributes that can be applied to any DOM element
194
 */
195
interface GlobalDOMAttributes<T = Element> extends GlobalDOMEvents<T> {
196
  dir?: string | undefined;
197
  lang?: string | undefined;
198
  hidden?: boolean | undefined;
199
  inert?: boolean | undefined;
200
  translate?: "yes" | "no" | undefined;
201
}
202

203
/** Any focusable element, including both HTML and SVG elements */
204
type FocusableElement = Element & HTMLOrSVGElement;
205
```
206

207
### Global DOM Events
208

209
Comprehensive DOM event handlers for mouse, touch, pointer, and other interactions.
210

211
```typescript { .api }
212
/**
213
 * Global DOM events supported on all DOM elements
214
 */
215
interface GlobalDOMEvents<T = Element> {
216
  // Mouse Events
217
  onClick?: MouseEventHandler<T> | undefined;
218
  onClickCapture?: MouseEventHandler<T> | undefined;
219
  onAuxClick?: MouseEventHandler<T> | undefined;
220
  onAuxClickCapture?: MouseEventHandler<T> | undefined;
221
  onContextMenu?: MouseEventHandler<T> | undefined;
222
  onContextMenuCapture?: MouseEventHandler<T> | undefined;
223
  onDoubleClick?: MouseEventHandler<T> | undefined;
224
  onDoubleClickCapture?: MouseEventHandler<T> | undefined;
225
  onMouseDown?: MouseEventHandler<T> | undefined;
226
  onMouseDownCapture?: MouseEventHandler<T> | undefined;
227
  onMouseEnter?: MouseEventHandler<T> | undefined;
228
  onMouseLeave?: MouseEventHandler<T> | undefined;
229
  onMouseMove?: MouseEventHandler<T> | undefined;
230
  onMouseMoveCapture?: MouseEventHandler<T> | undefined;
231
  onMouseOut?: MouseEventHandler<T> | undefined;
232
  onMouseOutCapture?: MouseEventHandler<T> | undefined;
233
  onMouseOver?: MouseEventHandler<T> | undefined;
234
  onMouseOverCapture?: MouseEventHandler<T> | undefined;
235
  onMouseUp?: MouseEventHandler<T> | undefined;
236
  onMouseUpCapture?: MouseEventHandler<T> | undefined;
237

238
  // Touch Events
239
  onTouchCancel?: TouchEventHandler<T> | undefined;
240
  onTouchCancelCapture?: TouchEventHandler<T> | undefined;
241
  onTouchEnd?: TouchEventHandler<T> | undefined;
242
  onTouchEndCapture?: TouchEventHandler<T> | undefined;
243
  onTouchMove?: TouchEventHandler<T> | undefined;
244
  onTouchMoveCapture?: TouchEventHandler<T> | undefined;
245
  onTouchStart?: TouchEventHandler<T> | undefined;
246
  onTouchStartCapture?: TouchEventHandler<T> | undefined;
247

248
  // Pointer Events
249
  onPointerDown?: PointerEventHandler<T> | undefined;
250
  onPointerDownCapture?: PointerEventHandler<T> | undefined;
251
  onPointerMove?: PointerEventHandler<T> | undefined;
252
  onPointerMoveCapture?: PointerEventHandler<T> | undefined;
253
  onPointerUp?: PointerEventHandler<T> | undefined;
254
  onPointerUpCapture?: PointerEventHandler<T> | undefined;
255
  onPointerCancel?: PointerEventHandler<T> | undefined;
256
  onPointerCancelCapture?: PointerEventHandler<T> | undefined;
257
  onPointerEnter?: PointerEventHandler<T> | undefined;
258
  onPointerLeave?: PointerEventHandler<T> | undefined;
259
  onPointerOver?: PointerEventHandler<T> | undefined;
260
  onPointerOverCapture?: PointerEventHandler<T> | undefined;
261
  onPointerOut?: PointerEventHandler<T> | undefined;
262
  onPointerOutCapture?: PointerEventHandler<T> | undefined;
263
  onGotPointerCapture?: PointerEventHandler<T> | undefined;
264
  onGotPointerCaptureCapture?: PointerEventHandler<T> | undefined;
265
  onLostPointerCapture?: PointerEventHandler<T> | undefined;
266
  onLostPointerCaptureCapture?: PointerEventHandler<T> | undefined;
267

268
  // UI Events
269
  onScroll?: UIEventHandler<T> | undefined;
270
  onScrollCapture?: UIEventHandler<T> | undefined;
271

272
  // Wheel Events
273
  onWheel?: WheelEventHandler<T> | undefined;
274
  onWheelCapture?: WheelEventHandler<T> | undefined;
275

276
  // Animation Events
277
  onAnimationStart?: AnimationEventHandler<T> | undefined;
278
  onAnimationStartCapture?: AnimationEventHandler<T> | undefined;
279
  onAnimationEnd?: AnimationEventHandler<T> | undefined;
280
  onAnimationEndCapture?: AnimationEventHandler<T> | undefined;
281
  onAnimationIteration?: AnimationEventHandler<T> | undefined;
282
  onAnimationIterationCapture?: AnimationEventHandler<T> | undefined;
283

284
  // Transition Events
285
  onTransitionCancel?: TransitionEventHandler<T> | undefined;
286
  onTransitionCancelCapture?: TransitionEventHandler<T> | undefined;
287
  onTransitionEnd?: TransitionEventHandler<T> | undefined;
288
  onTransitionEndCapture?: TransitionEventHandler<T> | undefined;
289
  onTransitionRun?: TransitionEventHandler<T> | undefined;
290
  onTransitionRunCapture?: TransitionEventHandler<T> | undefined;
291
  onTransitionStart?: TransitionEventHandler<T> | undefined;
292
  onTransitionStartCapture?: TransitionEventHandler<T> | undefined;
293
}
294
```
295

296
### DOM References
297

298
Reference types for DOM elements with additional methods for safe DOM access.
299

300
```typescript { .api }
301
/**
302
 * DOM ref value with safe DOM node access
303
 * @template T The type of HTML element
304
 */
305
interface DOMRefValue<T extends HTMLElement = HTMLElement> {
306
  /** Returns the DOM node or null if not available */
307
  UNSAFE_getDOMNode(): T | null;
308
}
309

310
/**
311
 * Focusable ref value with focus capabilities
312
 * @template T The type of HTML element for focus
313
 * @template D The type of HTML element for DOM access
314
 */
315
interface FocusableRefValue<T extends HTMLElement = HTMLElement, D extends HTMLElement = T> extends DOMRefValue<D> {
316
  /** Focus the element */
317
  focus(): void;
318
}
319

320
/**
321
 * Ref type for DOM elements
322
 * @template T The type of HTML element
323
 */
324
type DOMRef<T extends HTMLElement = HTMLElement> = Ref<DOMRefValue<T>>;
325

326
/**
327
 * Ref type for focusable elements
328
 * @template T The type of HTML element
329
 */
330
type FocusableRef<T extends HTMLElement = HTMLElement> = Ref<FocusableRefValue<T>>;
331

332
/**
333
 * Enhanced forwardRef type for generics support
334
 */
335
type forwardRefType = typeof forwardRef;
336

337
/**
338
 * Ref object interface
339
 * @template T The type of the ref value
340
 */
341
interface RefObject<T> {
342
  current: T;
343
}
344
```
345

346
**Usage Examples:**
347

348
```typescript
349
import { DOMProps, AriaLabelingProps, FocusableDOMProps } from "@react-types/shared";
350

351
// Basic DOM component
352
interface BasicComponentProps extends DOMProps {
353
  children: React.ReactNode;
354
}
355

356
// Accessible button with ARIA labeling
357
interface AccessibleButtonProps extends FocusableDOMProps, AriaLabelingProps {
358
  children: React.ReactNode;
359
  onPress?: () => void;
360
}
361

362
function AccessibleButton({ 
363
  id, 
364
  excludeFromTabOrder, 
365
  "aria-label": ariaLabel,
366
  "aria-describedby": ariaDescribedBy,
367
  children, 
368
  onPress 
369
}: AccessibleButtonProps) {
370
  return (
371
    <button
372
      id={id}
373
      tabIndex={excludeFromTabOrder ? -1 : undefined}
374
      aria-label={ariaLabel}
375
      aria-describedby={ariaDescribedBy}
376
      onClick={onPress}
377
    >
378
      {children}
379
    </button>
380
  );
381
}
382

383
// Text input with comprehensive DOM props
384
interface TextInputProps extends TextInputDOMProps {
385
  label?: string;
386
}
387

388
function TextInput({ 
389
  id, 
390
  name, 
391
  type = "text", 
392
  placeholder, 
393
  maxLength, 
394
  autoComplete,
395
  onInput,
396
  label 
397
}: TextInputProps) {
398
  return (
399
    <div>
400
      {label && <label htmlFor={id}>{label}</label>}
401
      <input
402
        id={id}
403
        name={name}
404
        type={type}
405
        placeholder={placeholder}
406
        maxLength={maxLength}
407
        autoComplete={autoComplete}
408
        onInput={onInput}
409
      />
410
    </div>
411
  );
412
}
413
```