Portal

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

Demos Components API

Introduction

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 Unstyled Modal and Unstyled Popper components.

Component

Usage

After installation, you can start building with this component using the following basic elements:

import Portal from '@mui/base/Portal';

export default function MyApp() {
  return (
    <Portal>{/* children to be rendered outside of the current DOM node */}</Portal>
  );
}

Basics

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 the Portal's 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} />

<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} />

Press Enter to start editing

Server-side

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

Portal API

Import

import Portal from '@mui/base/Portal';
// or
import { Portal } from '@mui/base';

You can learn about the difference by reading this guide on minimizing bundle size.

Props

Name	Type	Default	Description
children	node		The children to render into the `container`.
container	HTML element \| func		An HTML element or function that returns one. The `container` will have the portal children appended to it. By default, it uses the body of the top-level document object, so it's simply `document.body` most of the time.
disablePortal	bool	false	The `children` will be under the DOM hierarchy of the parent component.

The component cannot hold a ref.