1 | @# Overlay
|
2 |
|
3 | `Overlay` is a generic low-level component for rendering content _on top of_ its
|
4 | siblings, or above the entire application.
|
5 |
|
6 | It combines a [`Portal`](#core/components/portal), which allows JSX children to
|
7 | be rendered at a different place in the DOM tree, with a
|
8 | [`CSSTransition`](https://reactcommunity.org/react-transition-group/) to support
|
9 | elegant enter and leave transitions.
|
10 |
|
11 | An optional "backdrop" element can be rendered behind the overlaid children to
|
12 | provide modal behavior, whereby the overlay prevents interaction with anything
|
13 | behind it.
|
14 |
|
15 | `Overlay` is the backbone of all the components listed in the **Overlays** group
|
16 | in the sidebar. Using `Overlay` directly should be rare in your app; it should
|
17 | only be necessary if no existing component meets your needs.
|
18 |
|
19 | @reactExample OverlayExample
|
20 |
|
21 | @## Scroll support
|
22 |
|
23 | Overlays rely heavily on fixed and absolute positioning. By default, an overlay
|
24 | larger than the viewport will not be scrollable, so any overflowing content will
|
25 | be hidden. Fortunately, making an overlay scrollable is very easy: simply pass
|
26 | `Classes.OVERLAY_SCROLL_CONTAINER` as the Overlay `className`, and we'll take
|
27 | care of the rest.
|
28 |
|
29 | ```tsx
|
30 | <Overlay className={Classes.OVERLAY_SCROLL_CONTAINER} ... />
|
31 | ```
|
32 |
|
33 | The `Dialog` component applies this CSS class automatically.
|
34 |
|
35 | @## Props
|
36 |
|
37 | `Overlay` is a controlled component that renders its children only when
|
38 | `isOpen={true}`. The optional backdrop element will be inserted before the
|
39 | children if `hasBackdrop={true}`.
|
40 |
|
41 | The `onClose` callback prop is invoked when user interaction causes the overlay
|
42 | to close, but your application is responsible for updating the state that
|
43 | actually closes the overlay.
|
44 |
|
45 | <div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
|
46 | <h4 class="@ns-heading">A note about overlay content positioning</h4>
|
47 |
|
48 | When rendered inline, content will automatically be set to `position: absolute` to respect
|
49 | document flow. Otherwise, content will be set to `position: fixed` to cover the entire viewport.
|
50 | </div>
|
51 |
|
52 | ```tsx
|
53 | <div>
|
54 | <Button text="Show overlay" onClick={this.toggleOverlay} />
|
55 | <Overlay isOpen={this.state.isOpen} onClose={this.toggleOverlay}>
|
56 | Overlaid contents...
|
57 | </Overlay>
|
58 | </div>
|
59 | ```
|
60 |
|
61 | @interface IOverlayProps
|