0
# Overlay Components
1

2
Modal dialogs, popovers, tooltips, drawers, and overlay management components for complex user interactions.
3

4
## Capabilities
5

6
### Modal Component
7

8
Full-screen or centered modal dialog component.
9

10
```typescript { .api }
11
/**
12
 * Modal dialog component for overlaying content
13
 * @param props - Modal component props
14
 * @returns JSX element representing a modal dialog
15
 */
16
function Modal(props: IModalProps): JSX.Element;
17

18
interface IModalProps extends StyledProps {
19
  isOpen: boolean;
20
  onClose: () => void;
21
  initialFocusRef?: React.RefObject<any>;
22
  finalFocusRef?: React.RefObject<any>;
23
  avoidKeyboard?: boolean;
24
  closeOnOverlayClick?: boolean;
25
  isKeyboardDismissable?: boolean;
26
  overlayVisible?: boolean;
27
  backdropVisible?: boolean;
28
  animationPreset?: "slide" | "fade";
29
  size?: "xs" | "sm" | "md" | "lg" | "xl" | "full";
30
  children?: React.ReactNode;
31
  useRNModal?: boolean;
32
  _backdrop?: IBackdropProps;
33
  _fade?: IFadeProps;
34
  _slide?: ISlideProps;
35
}
36
```
37

38
**Usage Example:**
39

40
```typescript
41
import { Modal, Button, Text, VStack } from "native-base";
42

43
function ModalExample() {
44
  const [showModal, setShowModal] = React.useState(false);
45
  
46
  return (
47
    <>
48
      <Button onPress={() => setShowModal(true)}>Open Modal</Button>
49
      <Modal isOpen={showModal} onClose={() => setShowModal(false)}>
50
        <Modal.Content maxWidth="400px">
51
          <Modal.CloseButton />
52
          <Modal.Header>Contact us</Modal.Header>
53
          <Modal.Body>
54
            <VStack space={3}>
55
              <Text>Modal body content goes here</Text>
56
            </VStack>
57
          </Modal.Body>
58
          <Modal.Footer>
59
            <Button.Group space={2}>
60
              <Button variant="ghost" onPress={() => setShowModal(false)}>
61
                Cancel
62
              </Button>
63
              <Button onPress={() => setShowModal(false)}>
64
                Save
65
              </Button>
66
            </Button.Group>
67
          </Modal.Footer>
68
        </Modal.Content>
69
      </Modal>
70
    </>
71
  );
72
}
73
```
74

75
### Popover Component
76

77
Contextual popup component that appears relative to a trigger element.
78

79
```typescript { .api }
80
/**
81
 * Popover component for contextual content display
82
 * @param props - Popover component props
83
 * @returns JSX element representing a popover
84
 */
85
function Popover(props: IPopoverProps): JSX.Element;
86

87
interface IPopoverProps extends StyledProps {
88
  isOpen?: boolean;
89
  defaultIsOpen?: boolean;
90
  onOpen?: () => void;
91
  onClose?: () => void;
92
  trigger?: (props: any) => JSX.Element;
93
  placement?: 
94
    | "auto"
95
    | "auto-start"
96
    | "auto-end"
97
    | "top"
98
    | "top-start" 
99
    | "top-end"
100
    | "bottom"
101
    | "bottom-start"
102
    | "bottom-end"
103
    | "right"
104
    | "right-start"
105
    | "right-end"
106
    | "left"
107
    | "left-start"
108
    | "left-end";
109
  closeOnBlur?: boolean;
110
  initialFocusRef?: React.RefObject<any>;
111
  finalFocusRef?: React.RefObject<any>;
112
  isKeyboardDismissable?: boolean;
113
  shouldOverlapWithTrigger?: boolean;
114
  crossOffset?: number;
115
  offset?: number;
116
  children?: React.ReactNode;
117
  trapFocus?: boolean;
118
}
119
```
120

121
**Usage Example:**
122

123
```typescript
124
import { Popover, Button, Text, Box } from "native-base";
125

126
function PopoverExample() {
127
  return (
128
    <Popover 
129
      trigger={(triggerProps) => (
130
        <Button {...triggerProps}>Open Popover</Button>
131
      )}
132
    >
133
      <Popover.Content accessibilityLabel="Welcome Message" w="56">
134
        <Popover.Arrow />
135
        <Popover.CloseButton />
136
        <Popover.Header>Welcome!</Popover.Header>
137
        <Popover.Body>
138
          <Text>This is the popover content</Text>
139
        </Popover.Body>
140
        <Popover.Footer justifyContent="flex-end">
141
          <Button.Group size="xs">
142
            <Button variant="ghost">Cancel</Button>
143
            <Button>Apply</Button>
144
          </Button.Group>
145
        </Popover.Footer>
146
      </Popover.Content>
147
    </Popover>
148
  );
149
}
150
```
151

152
### Tooltip Component
153

154
Simple tooltip component for hover or focus states.
155

156
```typescript { .api }
157
/**
158
 * Tooltip component for contextual help text
159
 * @param props - Tooltip component props
160
 * @returns JSX element representing a tooltip
161
 */
162
function Tooltip(props: ITooltipProps): JSX.Element;
163

164
interface ITooltipProps extends StyledProps {
165
  label: string;
166
  children: React.ReactElement;
167
  isOpen?: boolean;
168
  defaultIsOpen?: boolean;
169
  onOpen?: () => void;
170
  onClose?: () => void;
171
  placement?: 
172
    | "auto"
173
    | "auto-start"
174
    | "auto-end"
175
    | "top"
176
    | "top-start" 
177
    | "top-end"
178
    | "bottom"
179
    | "bottom-start"
180
    | "bottom-end"
181
    | "right"
182
    | "right-start"
183
    | "right-end"
184
    | "left"
185
    | "left-start"
186
    | "left-end";
187
  hasArrow?: boolean;
188
  arrowSize?: number;
189
  arrowShadowColor?: string;
190
  bg?: ResponsiveValue<string>;
191
  backgroundColor?: ResponsiveValue<string>;
192
  openDelay?: number;
193
  closeDelay?: number;
194
  closeOnClick?: boolean;
195
  shouldWrapChildren?: boolean;
196
  offset?: number;
197
  crossOffset?: number;
198
  isDisabled?: boolean;
199
}
200
```
201

202
**Usage Example:**
203

204
```typescript
205
import { Tooltip, Button } from "native-base";
206

207
<Tooltip label="This is a tooltip" placement="top">
208
  <Button>Hover me</Button>
209
</Tooltip>
210
```
211

212
### Drawer Component
213

214
Side panel drawer component for navigation or content.
215

216
```typescript { .api }
217
/**
218
 * Drawer component for side panel content
219
 * @param props - Drawer component props
220
 * @returns JSX element representing a side drawer
221
 */
222
function Drawer(props: IDrawerProps): JSX.Element;
223

224
interface IDrawerProps extends StyledProps {
225
  isOpen: boolean;
226
  onClose: () => void;
227
  placement?: "top" | "right" | "bottom" | "left";
228
  size?: "xs" | "sm" | "md" | "lg" | "xl" | "full";
229
  initialFocusRef?: React.RefObject<any>;
230
  finalFocusRef?: React.RefObject<any>;
231
  isKeyboardDismissable?: boolean;
232
  overlayVisible?: boolean;
233
  backdropVisible?: boolean;
234
  closeOnOverlayClick?: boolean;
235
  children?: React.ReactNode;
236
  _backdrop?: IBackdropProps;
237
  _content?: IBoxProps;
238
  _body?: IBoxProps;
239
}
240
```
241

242
**Usage Example:**
243

244
```typescript
245
import { Drawer, Button, VStack } from "native-base";
246

247
function DrawerExample() {
248
  const [isOpen, setIsOpen] = React.useState(false);
249
  
250
  return (
251
    <>
252
      <Button onPress={() => setIsOpen(true)}>Open Drawer</Button>
253
      <Drawer isOpen={isOpen} onClose={() => setIsOpen(false)} size="md">
254
        <Drawer.Content>
255
          <Drawer.CloseButton />
256
          <Drawer.Header>Menu</Drawer.Header>
257
          <Drawer.Body>
258
            <VStack space={4}>
259
              <Button variant="ghost">Home</Button>
260
              <Button variant="ghost">About</Button>
261
              <Button variant="ghost">Contact</Button>
262
            </VStack>
263
          </Drawer.Body>
264
        </Drawer.Content>
265
      </Drawer>
266
    </>
267
  );
268
}
269
```
270

271
### AlertDialog Component
272

273
Alert dialog component for important confirmations or warnings.
274

275
```typescript { .api }
276
/**
277
 * Alert dialog component for critical user confirmations
278
 * @returns JSX element representing an alert dialog
279
 */
280
function AlertDialog(): JSX.Element;
281
```
282

283
### Actionsheet Component
284

285
Bottom sheet component for contextual actions on mobile.
286

287
```typescript { .api }
288
/**
289
 * Action sheet component for mobile-friendly action selection
290
 * @param props - Actionsheet component props
291
 * @returns JSX element representing a bottom action sheet
292
 */
293
function Actionsheet(props: IActionsheetProps): JSX.Element;
294

295
interface IActionsheetProps extends StyledProps {
296
  isOpen: boolean;
297
  onClose: () => void;
298
  hideDragIndicator?: boolean;
299
  size?: "xs" | "sm" | "md" | "lg" | "xl" | "full";
300
  disableOverlay?: boolean;
301
  children?: React.ReactNode;
302
  _backdrop?: IBackdropProps;
303
}
304

305
interface IActionsheetContentProps extends IBoxProps {
306
  children?: React.ReactNode;
307
}
308

309
interface IActionsheetItemProps extends IPressableProps {
310
  children?: React.ReactNode;
311
  isDisabled?: boolean;
312
  startIcon?: JSX.Element;
313
  endIcon?: JSX.Element;
314
  _text?: ITextProps;
315
  _icon?: IIconProps;
316
}
317
```
318

319
**Usage Example:**
320

321
```typescript
322
import { Actionsheet, Button, VStack, Text } from "native-base";
323

324
function ActionsheetExample() {
325
  const [isOpen, setIsOpen] = React.useState(false);
326
  
327
  return (
328
    <>
329
      <Button onPress={() => setIsOpen(true)}>Open Actionsheet</Button>
330
      <Actionsheet isOpen={isOpen} onClose={() => setIsOpen(false)}>
331
        <Actionsheet.Content>
332
          <VStack w="100%" space={2}>
333
            <Actionsheet.Item onPress={() => console.log("Delete")}>
334
              <Text>Delete</Text>
335
            </Actionsheet.Item>
336
            <Actionsheet.Item onPress={() => console.log("Share")}>
337
              <Text>Share</Text>
338
            </Actionsheet.Item>
339
            <Actionsheet.Item onPress={() => console.log("Edit")}>
340
              <Text>Edit</Text>
341
            </Actionsheet.Item>
342
          </VStack>
343
        </Actionsheet.Content>
344
      </Actionsheet>
345
    </>
346
  );
347
}
348
```
349

350
### Backdrop Component
351

352
Backdrop overlay component used by modals and other overlay components.
353

354
```typescript { .api }
355
/**
356
 * Backdrop component for overlay backgrounds
357
 * @returns JSX element representing overlay backdrop
358
 */
359
function Backdrop(): JSX.Element;
360

361
interface IBackdropProps extends IPressableProps {
362
  bg?: ResponsiveValue<string>;
363
  backgroundColor?: ResponsiveValue<string>;
364
  opacity?: ResponsiveValue<number>;
365
}
366
```
367

368
## Overlay Management Patterns
369

370
### Managing Multiple Overlays
371

372
When working with multiple overlays, consider z-index stacking and focus management:
373

374
```typescript
375
import { Modal, Popover, useDisclose } from "native-base";
376

377
function MultipleOverlaysExample() {
378
  const { isOpen: isModalOpen, onOpen: onModalOpen, onClose: onModalClose } = useDisclose();
379
  const { isOpen: isPopoverOpen, onOpen: onPopoverOpen, onClose: onPopoverClose } = useDisclose();
380
  
381
  return (
382
    <>
383
      <Button onPress={onModalOpen}>Open Modal</Button>
384
      
385
      <Modal isOpen={isModalOpen} onClose={onModalClose}>
386
        <Modal.Content>
387
          <Modal.Header>Modal with Popover</Modal.Header>
388
          <Modal.Body>
389
            <Popover 
390
              isOpen={isPopoverOpen} 
391
              onClose={onPopoverClose}
392
              trigger={(triggerProps) => (
393
                <Button {...triggerProps} onPress={onPopoverOpen}>
394
                  Open Popover
395
                </Button>
396
              )}
397
            >
398
              <Popover.Content>
399
                <Popover.Body>
400
                  <Text>Nested overlay content</Text>
401
                </Popover.Body>
402
              </Popover.Content>
403
            </Popover>
404
          </Modal.Body>
405
        </Modal.Content>
406
      </Modal>
407
    </>
408
  );
409
}
410
```
411

412
### Focus Management
413

414
Proper focus management for accessibility:
415

416
```typescript
417
import { Modal, Input } from "native-base";
418

419
function FocusManagedModal() {
420
  const [isOpen, setIsOpen] = React.useState(false);
421
  const initialRef = React.useRef(null);
422
  const finalRef = React.useRef(null);
423
  
424
  return (
425
    <>
426
      <Button ref={finalRef} onPress={() => setIsOpen(true)}>
427
        Open Modal
428
      </Button>
429
      
430
      <Modal 
431
        isOpen={isOpen} 
432
        onClose={() => setIsOpen(false)}
433
        initialFocusRef={initialRef}
434
        finalFocusRef={finalRef}
435
      >
436
        <Modal.Content>
437
          <Modal.Header>Focus Management</Modal.Header>
438
          <Modal.Body>
439
            <Input ref={initialRef} placeholder="This input gets focus" />
440
          </Modal.Body>
441
        </Modal.Content>
442
      </Modal>
443
    </>
444
  );
445
}
446
```