0
# Overlay Components
1
2
Modal and non-modal overlay components including dialogs, panels, callouts, and tooltips for displaying contextual information and actions over the main application content.
3
4
## Capabilities
5
6
### Panel
7
8
Slide-out side panel component for displaying detailed information or secondary actions without navigating away from the current context.
9
10
```typescript { .api }
11
/**
12
* Slide-out side panel component
13
*/
14
function Panel(props: IPanelProps): JSX.Element;
15
16
interface IPanel {
17
/** Open the panel */
18
open(): void;
19
/** Dismiss/close the panel */
20
dismiss(): void;
21
}
22
23
interface IPanelProps {
24
/** Reference to access component methods */
25
componentRef?: IRefObject<IPanel>;
26
/** Whether the panel is open */
27
isOpen?: boolean;
28
/** Whether the panel has a close button */
29
hasCloseButton?: boolean;
30
/** Whether clicking outside dismisses the panel */
31
isLightDismiss?: boolean;
32
/** Whether the panel is hidden when dismissed */
33
isHiddenOnDismiss?: boolean;
34
/** Whether the panel blocks interaction with main content */
35
isBlocking?: boolean;
36
/** Size/type of the panel */
37
type?: PanelType;
38
/** Custom width for custom panel type */
39
customWidth?: string;
40
/** Header text */
41
headerText?: string;
42
/** Properties for the header text element */
43
headerTextProps?: React.HTMLProps<HTMLDivElement>;
44
/** ARIA label for close button */
45
closeButtonAriaLabel?: string;
46
/** Whether panel is at the bottom on small screens */
47
isFooterAtBottom?: boolean;
48
/** Whether to show a subtle animation */
49
hasCloseButton?: boolean;
50
/** Layer properties */
51
layerProps?: ILayerProps;
52
/** Overlay properties */
53
overlayProps?: IOverlayProps;
54
/** Custom render function for navigation */
55
onRenderNavigation?: IRenderFunction<IPanelProps>;
56
/** Custom render function for header */
57
onRenderHeader?: IRenderFunction<IPanelProps>;
58
/** Custom render function for body */
59
onRenderBody?: IRenderFunction<IPanelProps>;
60
/** Custom render function for footer */
61
onRenderFooter?: IRenderFunction<IPanelProps>;
62
/** Custom render function for footer content */
63
onRenderFooterContent?: IRenderFunction<IPanelProps>;
64
/** Callback fired when panel is dismissed */
65
onDismiss?: (ev?: React.SyntheticEvent<HTMLElement>) => void;
66
/** Callback fired when panel opens */
67
onOpened?: () => void;
68
/** Callback fired when panel starts opening */
69
onOpening?: () => void;
70
/** Callback fired before panel dismisses */
71
onDismissed?: () => void;
72
/** Custom styles */
73
styles?: IStyleFunctionOrObject<IPanelStyleProps, IPanelStyles>;
74
/** Theme provided by higher-order component */
75
theme?: ITheme;
76
/** Additional CSS class */
77
className?: string;
78
/** Child content */
79
children?: React.ReactNode;
80
}
81
82
enum PanelType {
83
smallFluid = 0,
84
smallFixedFar = 1,
85
smallFixedNear = 2,
86
medium = 3,
87
large = 4,
88
largeFixed = 5,
89
extraLarge = 6,
90
custom = 99
91
}
92
```
93
94
**Usage Examples:**
95
96
```typescript
97
import React, { useState } from "react";
98
import { Panel, PanelType, PrimaryButton, DefaultButton } from "office-ui-fabric-react";
99
100
function BasicPanel() {
101
const [isOpen, setIsOpen] = useState(false);
102
103
return (
104
<div>
105
<PrimaryButton text="Open Panel" onClick={() => setIsOpen(true)} />
106
107
<Panel
108
isOpen={isOpen}
109
onDismiss={() => setIsOpen(false)}
110
headerText="Panel Title"
111
type={PanelType.medium}
112
closeButtonAriaLabel="Close panel"
113
>
114
<div>
115
<p>Panel content goes here.</p>
116
<DefaultButton text="Action" onClick={() => console.log("Action clicked")} />
117
</div>
118
</Panel>
119
</div>
120
);
121
}
122
123
function CustomPanel() {
124
const [isOpen, setIsOpen] = useState(false);
125
126
return (
127
<div>
128
<PrimaryButton text="Open Custom Panel" onClick={() => setIsOpen(true)} />
129
130
<Panel
131
isOpen={isOpen}
132
onDismiss={() => setIsOpen(false)}
133
type={PanelType.custom}
134
customWidth="600px"
135
headerText="Custom Width Panel"
136
isLightDismiss
137
onRenderFooter={() => (
138
<div style={{ padding: "16px", borderTop: "1px solid #edebe9" }}>
139
<PrimaryButton
140
text="Save"
141
onClick={() => {
142
console.log("Save clicked");
143
setIsOpen(false);
144
}}
145
/>
146
<DefaultButton
147
text="Cancel"
148
onClick={() => setIsOpen(false)}
149
style={{ marginLeft: 8 }}
150
/>
151
</div>
152
)}
153
>
154
<div style={{ padding: "16px" }}>
155
<p>Custom panel with footer actions.</p>
156
</div>
157
</Panel>
158
</div>
159
);
160
}
161
```
162
163
### Dialog
164
165
Modal dialog component for displaying important information or collecting user input that requires immediate attention.
166
167
```typescript { .api }
168
/**
169
* Modal dialog component for critical interactions
170
*/
171
function Dialog(props: IDialogProps): JSX.Element;
172
173
/**
174
* Content area of the dialog
175
*/
176
function DialogContent(props: IDialogContentProps): JSX.Element;
177
178
/**
179
* Footer area for dialog actions
180
*/
181
function DialogFooter(props: IDialogFooterProps): JSX.Element;
182
183
interface IDialog {
184
/** Focus on the dialog */
185
focus(): void;
186
}
187
188
interface IDialogProps {
189
/** Reference to access component methods */
190
componentRef?: IRefObject<IDialog>;
191
/** Whether the dialog is open */
192
isOpen?: boolean;
193
/** Whether the dialog blocks interaction with page */
194
isBlocking?: boolean;
195
/** Whether to use dark overlay */
196
isDarkOverlay?: boolean;
197
/** Dialog type */
198
type?: DialogType;
199
/** Maximum width of the dialog */
200
maxWidth?: number | string;
201
/** Minimum width of the dialog */
202
minWidth?: number | string;
203
/** Whether dialog is hidden on dismiss */
204
hidden?: boolean;
205
/** Modal properties */
206
modalProps?: IModalProps;
207
/** Title of the dialog */
208
title?: string;
209
/** Subtitle text */
210
subText?: string;
211
/** Content class name */
212
contentClassName?: string;
213
/** Top button properties */
214
topButtonsProps?: IButtonProps[];
215
/** Custom render function for title */
216
onRenderTitle?: IRenderFunction<IDialogProps>;
217
/** Custom render function for sub text */
218
onRenderSubText?: IRenderFunction<IDialogProps>;
219
/** Callback fired when dialog is dismissed */
220
onDismiss?: (ev?: React.MouseEvent<HTMLButtonElement>) => void;
221
/** Custom styles */
222
styles?: IStyleFunctionOrObject<IDialogStyleProps, IDialogStyles>;
223
/** Theme provided by higher-order component */
224
theme?: ITheme;
225
/** Additional CSS class */
226
className?: string;
227
/** Child content */
228
children?: React.ReactNode;
229
}
230
231
interface IDialogContentProps {
232
/** Reference to access component methods */
233
componentRef?: IRefObject<IDialogContent>;
234
/** Dialog title */
235
title?: string;
236
/** Dialog subtitle */
237
subText?: string;
238
/** Whether to show close button */
239
showCloseButton?: boolean;
240
/** Close button ARIA label */
241
closeButtonAriaLabel?: string;
242
/** Top button properties */
243
topButtonsProps?: IButtonProps[];
244
/** Custom render function for title */
245
onRenderTitle?: IRenderFunction<IDialogContentProps>;
246
/** Custom render function for sub text */
247
onRenderSubText?: IRenderFunction<IDialogContentProps>;
248
/** Callback fired when close button is clicked */
249
onDismiss?: (ev?: React.MouseEvent<HTMLButtonElement>) => void;
250
/** Custom styles */
251
styles?: IStyleFunctionOrObject<IDialogContentStyleProps, IDialogContentStyles>;
252
/** Theme provided by higher-order component */
253
theme?: ITheme;
254
/** Additional CSS class */
255
className?: string;
256
/** Child content */
257
children?: React.ReactNode;
258
}
259
260
interface IDialogFooterProps {
261
/** Reference to access component methods */
262
componentRef?: IRefObject<IDialogFooter>;
263
/** Custom styles */
264
styles?: IStyleFunctionOrObject<IDialogFooterStyleProps, IDialogFooterStyles>;
265
/** Theme provided by higher-order component */
266
theme?: ITheme;
267
/** Additional CSS class */
268
className?: string;
269
/** Child content (usually buttons) */
270
children?: React.ReactNode;
271
}
272
273
enum DialogType {
274
normal = 0,
275
largeHeader = 1,
276
close = 2
277
}
278
```
279
280
### Modal
281
282
Base modal component providing overlay functionality and focus management for dialog-like components.
283
284
```typescript { .api }
285
/**
286
* Base modal component for overlay functionality
287
*/
288
function Modal(props: IModalProps): JSX.Element;
289
290
interface IModal {
291
/** Focus on the modal */
292
focus(): void;
293
}
294
295
interface IModalProps {
296
/** Reference to access component methods */
297
componentRef?: IRefObject<IModal>;
298
/** Whether the modal is open */
299
isOpen?: boolean;
300
/** Whether the modal blocks interaction */
301
isBlocking?: boolean;
302
/** Whether to use dark overlay */
303
isDarkOverlay?: boolean;
304
/** Whether the modal is modeless */
305
isModeless?: boolean;
306
/** Container class name */
307
containerClassName?: string;
308
/** Scrollable content class name */
309
scrollableContentClassName?: string;
310
/** Drag options */
311
dragOptions?: IDragOptions;
312
/** Whether to enable touch bodyScroll */
313
enableAriaHiddenSiblings?: boolean;
314
/** Layer properties */
315
layerProps?: ILayerProps;
316
/** Overlay properties */
317
overlayProps?: IOverlayProps;
318
/** Title ID for ARIA */
319
titleAriaId?: string;
320
/** Subtitle ID for ARIA */
321
subtitleAriaId?: string;
322
/** Top offset */
323
topOffsetFixed?: boolean;
324
/** Custom render function for title */
325
onLayerDidMount?: () => void;
326
/** Callback fired when modal is dismissed */
327
onDismiss?: (ev?: React.MouseEvent<HTMLButtonElement>) => void;
328
/** Callback fired when modal is dismissed with overlay click */
329
onDismissed?: () => void;
330
/** Custom styles */
331
styles?: IStyleFunctionOrObject<IModalStyleProps, IModalStyles>;
332
/** Theme provided by higher-order component */
333
theme?: ITheme;
334
/** Additional CSS class */
335
className?: string;
336
/** Child content */
337
children?: React.ReactNode;
338
}
339
```
340
341
### Callout
342
343
Positioned overlay component for displaying contextual information relative to a target element.
344
345
```typescript { .api }
346
/**
347
* Positioned overlay component for contextual information
348
*/
349
function Callout(props: ICalloutProps): JSX.Element;
350
351
interface ICallout {
352
/** Dismiss the callout */
353
dismiss(ev?: any): void;
354
}
355
356
interface ICalloutProps {
357
/** Reference to access component methods */
358
componentRef?: IRefObject<ICallout>;
359
/** Target element or selector for positioning */
360
target?: Element | string | MouseEvent | React.RefObject<Element> | Point;
361
/** Directional hint for positioning */
362
directionalHint?: DirectionalHint;
363
/** Whether to use target width */
364
useTargetWidth?: boolean;
365
/** Whether to cover the target */
366
coverTarget?: boolean;
367
/** Gap between callout and target */
368
gapSpace?: number;
369
/** Beak width */
370
beakWidth?: number;
371
/** Minimum page padding */
372
minPagePadding?: number;
373
/** Whether the callout is hidden */
374
hidden?: boolean;
375
/** Role for accessibility */
376
role?: string;
377
/** ARIA label */
378
ariaLabel?: string;
379
/** ARIA labelledby */
380
ariaLabelledBy?: string;
381
/** ARIA describedby */
382
ariaDescribedBy?: string;
383
/** Set initial focus */
384
setInitialFocus?: boolean;
385
/** Whether to disable animation */
386
doNotLayer?: boolean;
387
/** Directional hint for RTL */
388
directionalHintForRTL?: DirectionalHint;
389
/** Callback fired when callout is positioned */
390
onPositioned?: (positions?: ICalloutPositionedInfo) => void;
391
/** Callback fired when callout is dismissed */
392
onDismiss?: (ev?: any) => void;
393
/** Callback fired when scroll occurs */
394
onScroll?: () => void;
395
/** Callback fired when callout tries to close */
396
onRestoreFocus?: () => void;
397
/** Custom styles */
398
styles?: IStyleFunctionOrObject<ICalloutContentStyleProps, ICalloutContentStyles>;
399
/** Theme provided by higher-order component */
400
theme?: ITheme;
401
/** Additional CSS class */
402
className?: string;
403
/** Callout bounds */
404
bounds?: IRectangle;
405
/** Background color */
406
backgroundColor?: string;
407
/** Prevention of dismiss on scroll */
408
preventDismissOnScroll?: boolean;
409
/** Prevention of dismiss on resize */
410
preventDismissOnResize?: boolean;
411
/** Prevention of dismiss on lost focus */
412
preventDismissOnLostFocus?: boolean;
413
/** Focus trap zone properties */
414
focusTrapZoneProps?: IFocusTrapZoneProps;
415
/** Whether to hide overflow */
416
hideOverflow?: boolean;
417
/** Child content */
418
children?: React.ReactNode;
419
}
420
421
enum DirectionalHint {
422
topLeftEdge = 0,
423
topCenter = 1,
424
topRightEdge = 2,
425
topAutoEdge = 3,
426
bottomLeftEdge = 4,
427
bottomCenter = 5,
428
bottomRightEdge = 6,
429
bottomAutoEdge = 7,
430
leftTopEdge = 8,
431
leftCenter = 9,
432
leftBottomEdge = 10,
433
rightTopEdge = 11,
434
rightCenter = 12,
435
rightBottomEdge = 13
436
}
437
```
438
439
### Tooltip
440
441
Simple tooltip component for providing brief contextual information on hover or focus.
442
443
```typescript { .api }
444
/**
445
* Simple tooltip for brief contextual information
446
*/
447
function Tooltip(props: ITooltipProps): JSX.Element;
448
449
/**
450
* Advanced tooltip host with overflow detection
451
*/
452
function TooltipHost(props: ITooltipHostProps): JSX.Element;
453
454
interface ITooltip {
455
/** Current tooltip props */
456
props: ITooltipProps;
457
}
458
459
interface ITooltipProps {
460
/** Reference to access component methods */
461
componentRef?: IRefObject<ITooltip>;
462
/** Content to display in tooltip */
463
content?: string | React.ReactNode;
464
/** Maximum width of tooltip */
465
maxWidth?: string | number;
466
/** Target ID for the tooltip */
467
targetElement?: HTMLElement;
468
/** Directional hint */
469
directionalHint?: DirectionalHint;
470
/** Gap space */
471
gapSpace?: number;
472
/** Beak width */
473
beakWidth?: number;
474
/** Delay before showing */
475
delay?: TooltipDelay;
476
/** Callout properties */
477
calloutProps?: ICalloutProps;
478
/** Custom render function for content */
479
onRenderContent?: IRenderFunction<ITooltipProps>;
480
/** Custom styles */
481
styles?: IStyleFunctionOrObject<ITooltipStyleProps, ITooltipStyles>;
482
/** Theme provided by higher-order component */
483
theme?: ITheme;
484
/** Additional CSS class */
485
className?: string;
486
}
487
488
interface ITooltipHostProps {
489
/** Reference to access component methods */
490
componentRef?: IRefObject<ITooltipHost>;
491
/** Content to display in tooltip */
492
content?: string | React.ReactNode;
493
/** Whether to show tooltip on overflow only */
494
overflowMode?: TooltipOverflowMode;
495
/** Maximum width of tooltip */
496
maxWidth?: string | number;
497
/** Directional hint */
498
directionalHint?: DirectionalHint;
499
/** Gap space */
500
gapSpace?: number;
501
/** Delay before showing */
502
delay?: TooltipDelay;
503
/** ID for the tooltip */
504
id?: string;
505
/** ARIA describedby */
506
setAriaDescribedBy?: boolean;
507
/** Tooltip properties */
508
tooltipProps?: ITooltipProps;
509
/** Callout properties */
510
calloutProps?: ICalloutProps;
511
/** Host class name */
512
hostClassName?: string;
513
/** Custom styles */
514
styles?: IStyleFunctionOrObject<ITooltipHostStyleProps, ITooltipHostStyles>;
515
/** Theme provided by higher-order component */
516
theme?: ITheme;
517
/** Additional CSS class */
518
className?: string;
519
/** Child content */
520
children?: React.ReactNode;
521
}
522
523
enum TooltipOverflowMode {
524
Parent = 0,
525
Self = 1
526
}
527
528
enum TooltipDelay {
529
zero = 0,
530
medium = 1,
531
long = 2
532
}
533
```
534
535
**Usage Examples:**
536
537
```typescript
538
import React, { useState } from "react";
539
import {
540
Dialog,
541
DialogContent,
542
DialogFooter,
543
Callout,
544
TooltipHost,
545
PrimaryButton,
546
DefaultButton,
547
DirectionalHint
548
} from "office-ui-fabric-react";
549
550
function DialogExample() {
551
const [isDialogOpen, setIsDialogOpen] = useState(false);
552
553
return (
554
<div>
555
<PrimaryButton text="Open Dialog" onClick={() => setIsDialogOpen(true)} />
556
557
<Dialog
558
isOpen={isDialogOpen}
559
onDismiss={() => setIsDialogOpen(false)}
560
isBlocking={false}
561
maxWidth={500}
562
>
563
<DialogContent
564
title="Confirm Action"
565
subText="Are you sure you want to proceed with this action?"
566
onDismiss={() => setIsDialogOpen(false)}
567
showCloseButton
568
>
569
<div>
570
<p>Additional details about the action can go here.</p>
571
</div>
572
</DialogContent>
573
574
<DialogFooter>
575
<PrimaryButton
576
text="Confirm"
577
onClick={() => {
578
console.log("Confirmed");
579
setIsDialogOpen(false);
580
}}
581
/>
582
<DefaultButton
583
text="Cancel"
584
onClick={() => setIsDialogOpen(false)}
585
/>
586
</DialogFooter>
587
</Dialog>
588
</div>
589
);
590
}
591
592
function CalloutExample() {
593
const [isCalloutVisible, setIsCalloutVisible] = useState(false);
594
const buttonRef = React.useRef<HTMLButtonElement>(null);
595
596
return (
597
<div>
598
<DefaultButton
599
ref={buttonRef}
600
text="Show Callout"
601
onClick={() => setIsCalloutVisible(!isCalloutVisible)}
602
/>
603
604
{isCalloutVisible && (
605
<Callout
606
target={buttonRef.current}
607
onDismiss={() => setIsCalloutVisible(false)}
608
directionalHint={DirectionalHint.bottomCenter}
609
setInitialFocus
610
>
611
<div style={{ padding: 16, maxWidth: 200 }}>
612
<h3>Callout Title</h3>
613
<p>This is the callout content with more detailed information.</p>
614
<DefaultButton
615
text="Close"
616
onClick={() => setIsCalloutVisible(false)}
617
/>
618
</div>
619
</Callout>
620
)}
621
</div>
622
);
623
}
624
625
function TooltipExample() {
626
return (
627
<div>
628
<TooltipHost content="This is a helpful tooltip">
629
<DefaultButton text="Hover for tooltip" />
630
</TooltipHost>
631
632
<TooltipHost
633
content="This tooltip only shows when text overflows"
634
overflowMode={TooltipOverflowMode.Self}
635
>
636
<div style={{ width: 100, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
637
This is a very long text that will be truncated
638
</div>
639
</TooltipHost>
640
</div>
641
);
642
}
643
```
644
645
## Types
646
647
```typescript { .api }
648
// Common overlay interfaces
649
interface IOverlayProps {
650
/** Whether overlay is dark */
651
isDarkThemed?: boolean;
652
/** Click handler */
653
onClick?: () => void;
654
/** Custom styles */
655
styles?: IStyleFunctionOrObject<IOverlayStyleProps, IOverlayStyles>;
656
/** Theme */
657
theme?: ITheme;
658
/** CSS class */
659
className?: string;
660
}
661
662
interface ILayerProps {
663
/** Host ID */
664
hostId?: string;
665
/** Event bus ID */
666
eventBubblingEnabled?: boolean;
667
/** Custom styles */
668
styles?: IStyleFunctionOrObject<ILayerStyleProps, ILayerStyles>;
669
/** Theme */
670
theme?: ITheme;
671
/** CSS class */
672
className?: string;
673
/** Callback when layer mounts */
674
onLayerDidMount?: () => void;
675
/** Callback when layer unmounts */
676
onLayerWillUnmount?: () => void;
677
}
678
679
interface IFocusTrapZoneProps {
680
/** Whether focus trap is disabled */
681
disabled?: boolean;
682
/** Element to focus initially */
683
firstFocusableSelector?: string;
684
/** Whether to force focus into zone */
685
forceFocusInsideTrap?: boolean;
686
/** Whether focus wraps around */
687
isClickableOutsideFocusTrap?: boolean;
688
/** Whether to ignore external focus */
689
ignoreExternalFocusing?: boolean;
690
/** Focus callback */
691
onFocus?: (event: React.FocusEvent<HTMLElement>) => void;
692
/** Blur callback */
693
onBlur?: (event: React.FocusEvent<HTMLElement>) => void;
694
}
695
696
// Positioning interfaces
697
interface Point {
698
x: number;
699
y: number;
700
}
701
702
interface IRectangle {
703
left: number;
704
top: number;
705
width: number;
706
height: number;
707
right?: number;
708
bottom?: number;
709
}
710
711
interface ICalloutPositionedInfo {
712
positions?: ICalloutPosition;
713
calloutMaxHeight?: number;
714
}
715
716
interface ICalloutPosition {
717
directionalHint?: DirectionalHint;
718
directionalHintFixed?: boolean;
719
alignmentEdge?: RectangleEdge;
720
targetEdge?: RectangleEdge;
721
}
722
723
enum RectangleEdge {
724
top = 1,
725
bottom = -1,
726
left = 2,
727
right = -2
728
}
729
```