Portal

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.

Examples

Default example

<Portal>
  Regardless of where this appears in the React component tree, this text will be rendered in the DOM within the portal
  root at document.body.
</Portal>

Customizing the portal root

<!-- 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:

1. Before rendering a <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.
2. Call the 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.

Multiple portal roots

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 default
                portal 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.

Props

Portal

function

string

Status

Alpha

• Component props are documented on primer.style/react.
• Component does not have any unnecessary third-party dependencies.
• N/A: Component can adapt to different themes.
• N/A: Component can adapt to different screen sizes.
• Component has 100% test coverage.

Beta

• Component is used in a production application.
• Common usage examples are documented on primer.style/react.
• Common usage examples are documented in storybook stories.
• Component has been reviewed by a systems designer and any resulting issues have been addressed.
• Component has been manually reviewed by the accessibility team and any resulting issues have been addressed.

Stable

• Component API has been stable with no breaking changes for at least one month.
• Feedback on API usability has been sought from developers using the component and any resulting issues have been addressed.
• Component has corresponding design guidelines documented in the interface guidelines.
• Component has corresponding Figma component in the Primer Web library.

Edit this page on GitHub

5 contributors

Last edited by rezrah on February 1, 2022