0
# React Stately Overlays
1

2
React Stately Overlays provides state management for overlay triggers in React applications. It's part of Adobe's React Spectrum ecosystem and follows the library's architectural pattern of separating state logic from UI implementation. The package exports a single hook that manages the open/closed state of overlays like popovers, tooltips, modals, and dropdowns.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { useOverlayTriggerState } from "@react-stately/overlays";
15
import type { OverlayTriggerProps, OverlayTriggerState } from "@react-stately/overlays";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { useOverlayTriggerState } = require("@react-stately/overlays");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import React from "react";
28
import { useOverlayTriggerState } from "@react-stately/overlays";
29

30
function PopoverTrigger() {
31
  // Uncontrolled usage
32
  const state = useOverlayTriggerState({
33
    defaultOpen: false,
34
    onOpenChange: (isOpen) => console.log('Overlay is now:', isOpen ? 'open' : 'closed')
35
  });
36

37
  return (
38
    <div>
39
      <button onClick={state.toggle}>
40
        {state.isOpen ? 'Close' : 'Open'} Popover
41
      </button>
42
      {state.isOpen && (
43
        <div className="popover">
44
          <p>Popover content</p>
45
          <button onClick={state.close}>Close</button>
46
        </div>
47
      )}
48
    </div>
49
  );
50
}
51

52
// Controlled usage
53
function ControlledOverlay() {
54
  const [isOpen, setIsOpen] = React.useState(false);
55
  
56
  const state = useOverlayTriggerState({
57
    isOpen,
58
    onOpenChange: setIsOpen
59
  });
60

61
  return (
62
    <div>
63
      <button onClick={state.toggle}>Toggle Modal</button>
64
      {state.isOpen && (
65
        <div className="modal">
66
          <p>Modal content</p>
67
          <button onClick={state.close}>Close</button>
68
        </div>
69
      )}
70
    </div>
71
  );
72
}
73
```
74

75
## Architecture
76

77
React Stately Overlays follows React Spectrum's separation of concerns pattern:
78

79
- **State Management Only**: No UI components, only state logic
80
- **Controlled/Uncontrolled Pattern**: Supports both controlled (external state) and uncontrolled (internal state) usage
81
- **React Hook Pattern**: Uses standard React hooks (`useCallback`, controlled state)
82
- **Type Safety**: Full TypeScript support with comprehensive type definitions
83
- **Zero Dependencies**: Minimal runtime dependencies, only peer depends on React
84

85
## Capabilities
86

87
### Overlay Trigger State Hook
88

89
Manages state for an overlay trigger, tracking whether the overlay is open and providing methods to control its visibility.
90

91
```typescript { .api }
92
/**
93
 * Manages state for an overlay trigger. Tracks whether the overlay is open, and provides
94
 * methods to toggle this state.
95
 */
96
function useOverlayTriggerState(props: OverlayTriggerProps): OverlayTriggerState;
97

98
interface OverlayTriggerProps {
99
  /** Whether the overlay is open by default (controlled). */
100
  isOpen?: boolean;
101
  /** Whether the overlay is open by default (uncontrolled). */
102
  defaultOpen?: boolean;
103
  /** Handler that is called when the overlay's open state changes. */
104
  onOpenChange?: (isOpen: boolean) => void;
105
}
106

107
interface OverlayTriggerState {
108
  /** Whether the overlay is currently open. */
109
  readonly isOpen: boolean;
110
  /** Sets whether the overlay is open. */
111
  setOpen(isOpen: boolean): void;
112
  /** Opens the overlay. */
113
  open(): void;
114
  /** Closes the overlay. */
115
  close(): void;
116
  /** Toggles the overlay's visibility. */
117
  toggle(): void;
118
}
119
```
120

121
**Usage Patterns:**
122

123
```typescript
124
// Uncontrolled - manages its own state
125
const state = useOverlayTriggerState({
126
  defaultOpen: false,
127
  onOpenChange: (isOpen) => {
128
    // Optional callback when state changes
129
    console.log('Overlay state changed:', isOpen);
130
  }
131
});
132

133
// Controlled - state managed externally
134
const [isModalOpen, setIsModalOpen] = React.useState(false);
135
const modalState = useOverlayTriggerState({
136
  isOpen: isModalOpen,
137
  onOpenChange: setIsModalOpen
138
});
139

140
// Access state and methods
141
console.log(state.isOpen); // current open/closed state
142
state.open();    // programmatically open
143
state.close();   // programmatically close
144
state.toggle();  // toggle current state
145
state.setOpen(true); // set specific state
146
```
147

148
The hook uses React's `useControlledState` utility internally to handle both controlled and uncontrolled modes seamlessly, and `useCallback` to ensure stable function references for optimal performance.