React Create Portal API

The createPortal API is part of the React DOM. It lets you render some children of a React component in another part of the DOM.

Useful when you need to create UIs such as tooltips, toasts, modals and popups.

How to use it

To create a portal, call createPortal, passing some JSX, and the DOM node where it should be rendered.

import { createPortal } from 'react-dom';

// ...

<div>
  <p>This child is placed in the parent div.</p>
  {createPortal(
    <p>This child is placed in the document body.</p>,
    document.body
  )}
</div>

Normally, a React component and its children have a parent-child relationship, and all of the children are nested within their parent after rendering.

However, with the createPortal API, a React component can render all or some of its children in another location in the DOM.
A portal only changes the physical placement of the DOM node. In every other way, the JSX you render into a portal acts as a child node of the React component that renders it.

Parameters

• children: anything that can be rendered with React, such as a piece of JSX or some component
• domNode: some DOM node, such as those returned by document.getElementById(). The node must already exist.
• optional: key a unique string or number to be used as the portal's key

Returns

createPortal returns a React node that can be included into JSX or returned from a React component. If React encounters it in the render output, it will placed the provided children inside the provided domNode.

Rendering to a different part of the DOM

import { createPortal } from 'react-dom';

function MyComponent() {
  return (
    <div style={{ border: '2px solid black' }}>
      <p>This child is placed in the parent div.</p>
      {createPortal(
        <p>This child is placed in the document body.</p>,
        document.body
      )}
    </div>
  );
}

React will put the DOM nodes for the JSX you passed inside of the DOM node provided.

Rendering a modal dialog with a portal

import React, { useState } from "react";
import { createPortal } from "react-dom";

function Modal({ onClose }) {
  return createPortal(
    <div className="modal">
      <p>This is a modal.</p>
      <button onClick={onClose}>Close</button>
    </div>,
    document.body,
  );
}

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div>
      <button onClick={() => setIsOpen(true)}>Open Modal</button>
      {isOpen && <Modal onClose={() => setIsOpen(false)} />}
    </div>
  );
}

To achieve accessibility, use ARIA roles and attributes.

function Modal({ onClose }) {
  return createPortal(
    <div role="dialog" aria-modal="true" className="modal">
      <p>This is a modal.</p>
      <button onClick={onClose}>Close</button>
    </div>,
    document.body,
  );
}

Pros of the createPortal API

• Rendering an element in another location in the DOM outside its parent
• Helps building certain UIs such as tooltips, and modals.
• Portals allow modals to escape their parent's constraints, ensuring they are not clipped by overflow:hidden or positioned incorrectly due to z-index issues.
• A right click menu no longer confined by the parent component's layout using a Portal