Portal

The Portal component lets you render its children into a DOM node that exists outside of its own DOM hierarchy.

Portal is a utility component built around React's createPortal() API. It gives you the functionality of createPortal() in a convenient component form.

The Portal component is used internally by the ModalUnstyled and Popper components.

Basic usage

Normally, children of a component are rendered within that component's DOM tree. But sometimes it's necessary to mount a child at a different location in the DOM.

The Portal component accepts a container prop that passes a ref to the DOM node where its children will be mounted.

The following demo shows how a <span> nested within a Portal can be appended to a node outside of its own DOM hierarchy—click Mount children to see how it behaves:

It looks like I will render here.

<button type="button" onClick={handleClick}>
  {show ? 'Unmount children' : 'Mount children'}
</button>
<Box sx={{ p: 1, my: 1, border: '1px solid' }}>
  It looks like I will render here.
  {show ? (
    <Portal container={container.current}>
      <span>But I actually render here!</span>
    </Portal>
  ) : null}
</Box>
<Box sx={{ p: 1, my: 1, border: '1px solid' }} ref={container} />

Server-side

The Portal component cannot be used to render child elements on the server—client-side hydration is necessary.

API

<Portal />