Portal
Portals allow you to create a separation between the logical React component hierarchy and the physical DOM.
- Alpha
- Not reviewed for accessibility
import {Portal, registerPortalRoot} from '@primer/react'
This Portal component will render all children into the portal root DOM node instead of as children of this Portal's parent DOM element. This is useful for breaking out of the current stacking context. For example, popup menus and tooltips may need to render on top of (read: covering up) other UI. The best way to guarantee this is to add these elements to top-level DOM, such as directly on document.body. These elements can then be moved to the correct location using absolute positioning.
See the React documentation on portals for an in-depth explanation.
<Portal>Regardless of where this appears in the React component tree, this text will be rendered in the DOM within the portalroot at document.body.</Portal>
<!-- Wherever in your DOM tree you would like to have the default portal root --><div id="__primerPortalRoot__"></div>
or
import { registerPortalRoot } from "@primer/react"registerPortalRoot(document.querySelector(".my-portal-root")!)
By default, Primer will create a portal root for you as a child of the closest <BaseStyles> element, or document.body if none is found. That root will be positioned absolutely in the top-left corner of its parent element. If you would like to specify your own portal root, there are two options:
<Portal> for the first time, ensure that an element exists with id __primerPortalRoot__. If that exists, it will be used as the default portal root.registerPortalRoot function, passing in the element you would like to use as your default portal root.Keep in mind that any inherited styles applied to portaled elements are based on its physical DOM parent. Practically this means that styles added by a <BaseStyles> element will not apply to the portaled content unless the portal root is a descendent of a <BaseStyles> element.
Also, as <ThemeProvider> affects the React context, which applies to the logical React component hierarchy, the portal root is not required to be a child of a <ThemeProvider> for its children to receive that context.
import { Portal, registerPortalRoot } from "@primer/react"registerPortalRoot(document.querySelector(".scrolling-canvas-root")!, "scrolling-canvas")// ...export default () => (<Portal containerName="scrolling-canvas"><div>This div will be rendered into the element registered above.</div><Portal><div>This div will be rendered into the defaultportal root created at document.body</div></Portal></Portal>)
There may be situations where you want to have multiple portal roots. Advanced scenarios may necessitate multiple stacking contexts for overlays. You can set up multiple roots using the registerPortalRoot function. Calling this function with an element and a string name will register the root, which can then be used by creating a <Portal> with a name prop matching the one you registered.
| Name | Type | Default | Description |
|---|---|---|---|
| onMount | function | Called when this portal is added to the DOM | |
| containerName | string | Renders the portal children into the container registered with the given name. If omitted, children are rendered into the default portal root. |