Overlay2 migration

Overlay in Blueprint v6.0 features some breaking changes compared to previous versions. To help you migrate to the new component, we've provided a new component called Overlay2 in @blueprintjs/core v5.9.0+.

Notable changes compared to Overlay

• The children of <Overlay2> must be native DOM elements or utilize React.forwardRef() to forward any injected ref to their underlying DOM element(s).
• For single-child overlays:
  • if you attach your own ref to the child, you must pass the same React.RefObject<HTMLElement> value to <Overlay2> via the childRef prop (we need this to forward along to <CSSTransition>).
• For overlays with multiple child elements:
  • regardless of whether you need your own ref on the child elements, you must enumerate a collection of refs for each of these elements and pass the collection along as a record (keyed by the elements' corresponding React key values) to <Overlay2 childRefs={...}>.

Changes for all overlay-based components (Overlay2, Dialog, Drawer, Popover, Omnibar)

These components rely on global state for some focus management and scrolling interaction functionality. Previously, this state was stored in a module-level global variable. Overlay2 utilizes a safer pattern for this global state via the new OverlaysProvider context provider.

In Blueprint v5.9+, applications which use overlay-based components are highly recommended to add an <OverlaysProvider> near the root of their application. This is optional (overlays will continue to work without it).

In Blueprint v6.0, <OverlaysProvider> will be required for all users of overlay-based components.

ReactDOM.render(
+ <OverlaysProvider>
    <HotkeysProvider>
      <App />
    </HotkeysProvider>
+ </OverlaysProvider>,
  document.querySelector("#root"),
)

Important: <OverlaysProvider> must come first (wrap around) <HotkeysProvider> so that the latter context can properly render the global hotkeys dialog which relies on overlays.