react-test/docs/data/material/components/portal/portal.md

productId, title, components, githubLabel

productId	title	components	githubLabel
material-ui	React Portal component	Portal	scope: portal

Portal

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

{{"component": "@mui/docs/ComponentLinkHeader", "design": false}}

Introduction

Portal is a utility component built around React's createPortal() API. It gives you the functionality of createPortal() in a convenient component form. It's used internally by the Modal and Popper components.

:::info According to the React docs, portals are useful when "you need the child element to visually 'break out' of its container"—for instance, modals and tooltips, which need to exist outside of the normal flow of the document. :::

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:

{{"demo": "SimplePortal.js"}}

Basics

Import

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

Customization

Server-side Portals

The DOM API isn't available on the server, so you need to use the container prop callback. This callback is called during a React layout effect:

<Portal container={() => document.getElementById('filter-panel')!}>
  <Child />
</Portal>

:::error The Portal component cannot be used to render child elements on the server—client-side hydration is necessary. This is because React doesn't support the createPortal() API on the server. See this GitHub issue for details. :::