0
# @react-types/overlays
1

2
@react-types/overlays provides comprehensive TypeScript type definitions for overlay components in React Spectrum, Adobe's design system. It defines interfaces and types for positioning overlays (modals, popovers, trays) including placement options, positioning properties, and trigger behaviors.
3

4
## Package Information
5

6
- **Package Name**: @react-types/overlays
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @react-types/overlays`
10
- **Peer Dependencies**: React ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
11

12
## Core Imports
13

14
```typescript
15
import type { 
16
  Placement, 
17
  PositionProps, 
18
  ModalProps, 
19
  PopoverProps, 
20
  TrayProps,
21
  OverlayTriggerProps 
22
} from "@react-types/overlays";
23
```
24

25
For specific imports:
26

27
```typescript
28
import type { Placement, PositionProps } from "@react-types/overlays";
29
import type { ModalProps } from "@react-types/overlays";
30
```
31

32
## Basic Usage
33

34
```typescript
35
import type { ModalProps, PopoverProps, Placement } from "@react-types/overlays";
36

37
// Define a modal component
38
function MyModal(props: ModalProps) {
39
  return (
40
    <div>
41
      {props.children}
42
    </div>
43
  );
44
}
45

46
// Define a popover component with placement
47
function MyPopover(props: PopoverProps & { placement: Placement }) {
48
  return (
49
    <div>
50
      {props.children}
51
    </div>
52
  );
53
}
54

55
// Usage with type safety
56
const modalProps: ModalProps = {
57
  children: <div>Modal content</div>,
58
  isOpen: true,
59
  onClose: () => console.log('closed'),
60
  type: 'modal',
61
  isDismissable: true
62
};
63
```
64

65
## Architecture
66

67
@react-types/overlays is built around several key type categories:
68

69
- **Placement Types**: Define where overlays appear relative to their anchors
70
- **Position Props**: Control overlay positioning behavior and calculations
71
- **Component Props**: Specific interfaces for modal, popover, and tray components
72
- **Trigger Props**: Handle overlay open/close state management
73
- **Base Types**: Foundation interfaces extended by specific component types
74

75
## Capabilities
76

77
### Placement Types
78

79
Core types for defining overlay positioning and placement relative to anchor elements.
80

81
```typescript { .api }
82
type Placement = 
83
  | 'bottom' | 'bottom left' | 'bottom right' | 'bottom start' | 'bottom end'
84
  | 'top' | 'top left' | 'top right' | 'top start' | 'top end'
85
  | 'left' | 'left top' | 'left bottom' | 'start' | 'start top' | 'start bottom'
86
  | 'right' | 'right top' | 'right bottom' | 'end' | 'end top' | 'end bottom';
87

88
type Axis = 'top' | 'bottom' | 'left' | 'right';
89
type SizeAxis = 'width' | 'height';
90
type PlacementAxis = Axis | 'center';
91
```
92

93
### Position Configuration
94

95
Interface for configuring overlay positioning behavior including placement, offsets, and flipping behavior.
96

97
```typescript { .api }
98
interface PositionProps {
99
  /**
100
   * The placement of the element with respect to its anchor element.
101
   * @default 'bottom'
102
   */
103
  placement?: Placement;
104
  /**
105
   * The placement padding that should be applied between the element and its
106
   * surrounding container.
107
   * @default 12
108
   */
109
  containerPadding?: number;
110
  /**
111
   * The additional offset applied along the main axis between the element and its
112
   * anchor element.
113
   * @default 0
114
   */
115
  offset?: number;
116
  /**
117
   * The additional offset applied along the cross axis between the element and its
118
   * anchor element.
119
   * @default 0
120
   */
121
  crossOffset?: number;
122
  /**
123
   * Whether the element should flip its orientation (e.g. top to bottom or left to right) when
124
   * there is insufficient room for it to render completely.
125
   * @default true
126
   */
127
  shouldFlip?: boolean;
128
  /** Whether the element is rendered. */
129
  isOpen?: boolean;
130
}
131
```
132

133
### Base Overlay Props
134

135
Base interface for all overlay components providing common functionality like lifecycle callbacks and focus management.
136

137
```typescript { .api }
138
interface OverlayProps {
139
  children: ReactNode;
140
  isOpen?: boolean;
141
  container?: Element;
142
  isKeyboardDismissDisabled?: boolean;
143
  onEnter?: () => void;
144
  onEntering?: () => void;
145
  onEntered?: () => void;
146
  onExit?: () => void;
147
  onExiting?: () => void;
148
  onExited?: () => void;
149
  nodeRef: MutableRefObject<HTMLElement | null>;
150
  disableFocusManagement?: boolean;
151
  shouldContainFocus?: boolean;
152
}
153
```
154

155
### Modal Props
156

157
Props interface for modal overlay components supporting different modal types and dismissal behavior.
158

159
```typescript { .api }
160
interface ModalProps extends StyleProps, Omit<OverlayProps, 'nodeRef'> {
161
  children: ReactElement;
162
  isOpen?: boolean;
163
  onClose?: () => void;
164
  type?: 'modal' | 'fullscreen' | 'fullscreenTakeover';
165
  isDismissable?: boolean;
166
}
167
```
168

169
### Popover Props
170

171
Props interface for popover overlay components with arrow support and placement options.
172

173
```typescript { .api }
174
interface PopoverProps extends StyleProps, Omit<OverlayProps, 'nodeRef'> {
175
  children: ReactNode;
176
  placement?: PlacementAxis;
177
  arrowProps?: HTMLAttributes<HTMLElement>;
178
  hideArrow?: boolean;
179
  isOpen?: boolean;
180
  onClose?: () => void;
181
  shouldCloseOnBlur?: boolean;
182
  isNonModal?: boolean;
183
  isDismissable?: boolean;
184
}
185
```
186

187
### Tray Props
188

189
Props interface for tray/drawer overlay components with height control and modal behavior options.
190

191
```typescript { .api }
192
interface TrayProps extends StyleProps, Omit<OverlayProps, 'nodeRef'> {
193
  children: ReactElement;
194
  isOpen?: boolean;
195
  onClose?: () => void;
196
  shouldCloseOnBlur?: boolean;
197
  isFixedHeight?: boolean;
198
  isNonModal?: boolean;
199
}
200
```
201

202
### Overlay Trigger Props
203

204
Props interface for components that trigger overlay open/close states with controlled and uncontrolled patterns.
205

206
```typescript { .api }
207
interface OverlayTriggerProps {
208
  /** Whether the overlay is open by default (controlled). */
209
  isOpen?: boolean;
210
  /** Whether the overlay is open by default (uncontrolled). */
211
  defaultOpen?: boolean;
212
  /** Handler that is called when the overlay's open state changes. */
213
  onOpenChange?: (isOpen: boolean) => void;
214
}
215
```
216

217
## Imported Types
218

219
```typescript { .api }
220
// From React
221
import type { 
222
  HTMLAttributes, 
223
  MutableRefObject, 
224
  ReactElement, 
225
  ReactNode 
226
} from 'react';
227

228
// From @react-types/shared  
229
import type { StyleProps } from '@react-types/shared';
230
```
231

232
## Type Dependencies
233

234
This package extends `StyleProps` from `@react-types/shared`, which provides comprehensive styling properties including:
235

236
- Layout properties (margin, padding, width, height)
237
- Flexbox and grid layout
238
- Positioning and z-index
239
- Border and background styling
240
- Responsive design support
241
- Accessibility and interaction states