UNPKG

6.2 kBTypeScriptView Raw
1/// <reference types="react" />
2import type { Props } from "../../common/props";
3export interface OverlayableProps extends OverlayLifecycleProps {
4 /**
5 * Whether the overlay should acquire application focus when it first opens.
6 *
7 * @default true
8 */
9 autoFocus?: boolean;
10 /**
11 * Whether pressing the `esc` key should invoke `onClose`.
12 *
13 * @default true
14 */
15 canEscapeKeyClose?: boolean;
16 /**
17 * Whether the overlay should prevent focus from leaving itself. That is, if the user attempts
18 * to focus an element outside the overlay and this prop is enabled, then the overlay will
19 * immediately bring focus back to itself. If you are nesting overlay components, either disable
20 * this prop on the "outermost" overlays or mark the nested ones `usePortal={false}`.
21 *
22 * @default true
23 */
24 enforceFocus?: boolean;
25 /**
26 * If `true` and `usePortal={true}`, the `Portal` containing the children is created and attached
27 * to the DOM when the overlay is opened for the first time; otherwise this happens when the
28 * component mounts. Lazy mounting provides noticeable performance improvements if you have lots
29 * of overlays at once, such as on each row of a table.
30 *
31 * @default true
32 */
33 lazy?: boolean;
34 /**
35 * Whether the application should return focus to the last active element in the
36 * document after this overlay closes.
37 *
38 * @default true
39 */
40 shouldReturnFocusOnClose?: boolean;
41 /**
42 * Indicates how long (in milliseconds) the overlay's enter/leave transition takes.
43 * This is used by React `CSSTransition` to know when a transition completes and must match
44 * the duration of the animation in CSS. Only set this prop if you override Blueprint's default
45 * transitions with new transitions of a different length.
46 *
47 * @default 300
48 */
49 transitionDuration?: number;
50 /**
51 * Whether the overlay should be wrapped in a `Portal`, which renders its contents in a new
52 * element attached to `portalContainer` prop.
53 *
54 * This prop essentially determines which element is covered by the backdrop: if `false`,
55 * then only its parent is covered; otherwise, the entire page is covered (because the parent
56 * of the `Portal` is the `<body>` itself).
57 *
58 * Set this prop to `false` on nested overlays (such as `Dialog` or `Popover`) to ensure that they
59 * are rendered above their parents.
60 *
61 * @default true
62 */
63 usePortal?: boolean;
64 /**
65 * Space-delimited string of class names applied to the `Portal` element if
66 * `usePortal={true}`.
67 */
68 portalClassName?: string;
69 /**
70 * The container element into which the overlay renders its contents, when `usePortal` is `true`.
71 * This prop is ignored if `usePortal` is `false`.
72 *
73 * @default document.body
74 */
75 portalContainer?: HTMLElement;
76 /**
77 * A list of DOM events which should be stopped from propagating through the Portal.
78 * This prop is ignored if `usePortal` is `false`.
79 *
80 * @deprecated this prop's implementation no longer works in React v17+
81 * @see https://legacy.reactjs.org/docs/portals.html#event-bubbling-through-portals
82 * @see https://github.com/palantir/blueprint/issues/6124
83 * @see https://github.com/palantir/blueprint/issues/6580
84 */
85 portalStopPropagationEvents?: Array<keyof HTMLElementEventMap>;
86 /**
87 * A callback that is invoked when user interaction causes the overlay to close, such as
88 * clicking on the overlay or pressing the `esc` key (if enabled).
89 *
90 * Receives the event from the user's interaction, if there was an event (generally either a
91 * mouse or key event). Note that, since this component is controlled by the `isOpen` prop, it
92 * will not actually close itself until that prop becomes `false`.
93 */
94 onClose?: (event: React.SyntheticEvent<HTMLElement>) => void;
95}
96export interface OverlayLifecycleProps {
97 /**
98 * Lifecycle method invoked just before the CSS _close_ transition begins on
99 * a child. Receives the DOM element of the child being closed.
100 */
101 onClosing?: (node: HTMLElement) => void;
102 /**
103 * Lifecycle method invoked just after the CSS _close_ transition ends but
104 * before the child has been removed from the DOM. Receives the DOM element
105 * of the child being closed.
106 */
107 onClosed?: (node: HTMLElement) => void;
108 /**
109 * Lifecycle method invoked just after mounting the child in the DOM but
110 * just before the CSS _open_ transition begins. Receives the DOM element of
111 * the child being opened.
112 */
113 onOpening?: (node: HTMLElement) => void;
114 /**
115 * Lifecycle method invoked just after the CSS _open_ transition ends.
116 * Receives the DOM element of the child being opened.
117 */
118 onOpened?: (node: HTMLElement) => void;
119}
120export interface BackdropProps {
121 /** CSS class names to apply to backdrop element. */
122 backdropClassName?: string;
123 /** HTML props for the backdrop element. */
124 backdropProps?: React.HTMLProps<HTMLDivElement>;
125 /**
126 * Whether clicking outside the overlay element (either on backdrop when present or on document)
127 * should invoke `onClose`.
128 *
129 * @default true
130 */
131 canOutsideClickClose?: boolean;
132 /**
133 * Whether a container-spanning backdrop element should be rendered behind the contents.
134 * When `false`, users will be able to scroll through and interact with overlaid content.
135 *
136 * @default true
137 */
138 hasBackdrop?: boolean;
139}
140export interface OverlayProps extends OverlayableProps, BackdropProps, Props {
141 /** Element to overlay. */
142 children?: React.ReactNode;
143 /**
144 * Toggles the visibility of the overlay and its children.
145 * This prop is required because the component is controlled.
146 */
147 isOpen: boolean;
148 /**
149 * Name of the transition for internal `CSSTransition`.
150 * Providing your own name here will require defining new CSS transition properties.
151 *
152 * @default Classes.OVERLAY
153 */
154 transitionName?: string;
155}