0
# React Aria Visually Hidden
1

2
React Aria Visually Hidden provides React components and hooks for creating visually hidden content that remains accessible to screen readers and assistive technologies. It offers a VisuallyHidden React component that renders content invisible to sighted users but maintains semantic structure for accessibility tools, and a useVisuallyHidden hook that provides the underlying CSS styling and focus management logic.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { VisuallyHidden, useVisuallyHidden } from "@react-aria/visually-hidden";
15
import type { VisuallyHiddenProps, VisuallyHiddenAria } from "@react-aria/visually-hidden";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { VisuallyHidden, useVisuallyHidden } = require("@react-aria/visually-hidden");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import React from "react";
28
import { VisuallyHidden, useVisuallyHidden } from "@react-aria/visually-hidden";
29

30
// Using the component
31
function SkipLink() {
32
  return (
33
    <VisuallyHidden isFocusable>
34
      <a href="#main">Skip to main content</a>
35
    </VisuallyHidden>
36
  );
37
}
38

39
// Using the hook
40
function CustomHiddenElement() {
41
  const { visuallyHiddenProps } = useVisuallyHidden({
42
    isFocusable: true
43
  });
44
  
45
  return (
46
    <div {...visuallyHiddenProps}>
47
      Screen reader only content
48
    </div>
49
  );
50
}
51
```
52

53
## Capabilities
54

55
### VisuallyHidden Component
56

57
React component that hides its children visually while keeping content visible to screen readers.
58

59
```typescript { .api }
60
/**
61
 * VisuallyHidden hides its children visually, while keeping content visible
62
 * to screen readers.
63
 */
64
function VisuallyHidden(props: VisuallyHiddenProps): JSX.Element;
65
```
66

67
**Usage Example:**
68

69
```typescript
70
import { VisuallyHidden } from "@react-aria/visually-hidden";
71

72
// Basic hidden content
73
<VisuallyHidden>
74
  <span>This text is hidden visually but available to screen readers</span>
75
</VisuallyHidden>
76

77
// Focusable hidden content (like skip links)
78
<VisuallyHidden isFocusable>
79
  <a href="#main">Skip to main content</a>
80
</VisuallyHidden>
81

82
// Custom element type
83
<VisuallyHidden elementType="span">
84
  <input type="checkbox" />
85
</VisuallyHidden>
86
```
87

88
### useVisuallyHidden Hook
89

90
Provides props for an element that hides its children visually but keeps content visible to assistive technology.
91

92
```typescript { .api }
93
/**
94
 * Provides props for an element that hides its children visually
95
 * but keeps content visible to assistive technology.
96
 */
97
function useVisuallyHidden(props: VisuallyHiddenProps = {}): VisuallyHiddenAria;
98
```
99

100
**Usage Example:**
101

102
```typescript
103
import { useVisuallyHidden } from "@react-aria/visually-hidden";
104

105
function CustomComponent() {
106
  const { visuallyHiddenProps } = useVisuallyHidden({
107
    isFocusable: true,
108
    style: { backgroundColor: 'red' } // Custom styles when focused
109
  });
110
  
111
  return (
112
    <div {...visuallyHiddenProps}>
113
      Hidden content with custom styling
114
    </div>
115
  );
116
}
117
```
118

119
## Types
120

121
```typescript { .api }
122
// Base types from React and @react-types/shared
123
import type { ReactNode, JSXElementConstructor } from 'react';
124
import type { DOMAttributes } from '@react-types/shared';
125

126
interface VisuallyHiddenProps extends DOMAttributes {
127
  /** The content to visually hide. */
128
  children?: ReactNode;
129
  
130
  /**
131
   * The element type for the container.
132
   * @default 'div'
133
   */
134
  elementType?: string | JSXElementConstructor<any>;
135
  
136
  /** Whether the element should become visible on focus, for example skip links. */
137
  isFocusable?: boolean;
138
}
139

140
interface VisuallyHiddenAria {
141
  /** Props to spread onto the element that should be hidden */
142
  visuallyHiddenProps: DOMAttributes;
143
}
144
```
145

146
## Important Notes
147

148
- **Positioning Requirements**: VisuallyHidden uses absolute positioning, so it needs a positioned ancestor to prevent scroll bars. Ensure a parent element has `position: relative` or another positioned value.
149
- **Focus Behavior**: When `isFocusable` is true, the element becomes visible when focused, useful for skip links and keyboard navigation aids.
150
- **CSS Implementation**: Uses CSS clipping and positioning techniques (`clip: rect(0 0 0 0)`, `clipPath: inset(50%)`) to hide content while preserving it in the accessibility tree.
151
- **Integration**: Part of the React Aria ecosystem and integrates with React Aria's focus management system through `useFocusWithin`.
152

153
## Dependencies
154

155
- **@react-aria/interactions**: For focus management via `useFocusWithin`
156
- **@react-aria/utils**: For utility functions like `mergeProps`
157
- **@react-types/shared**: For TypeScript interfaces like `DOMAttributes`
158
- **React**: Peer dependency (^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1)
159
- **React DOM**: Peer dependency (^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1)