0Pricing
React Academy · Lesson

What Are React Portals?

Understand the createPortal API and why rendering outside the root div is useful.

What Are React Portals? is a free React Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the React Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Welcome

In this lesson you will learn what React Portals are, why rendering outside the parent DOM tree is useful, and how to use the createPortal API.

The Normal React DOM Hierarchy

By default, every component renders inside its parent's DOM node. The entire React app usually lives inside one `
`. This works fine until you need a modal, tooltip, or dropdown to escape a parent with `overflow: hidden`.

What Is a Portal?

A **Portal** lets you render a component's output into a different DOM node — one that exists outside the React root. The component's React tree is unchanged; only the DOM position changes.
import { createPortal } from 'react-dom';

function Modal({ children }) {
  return createPortal(
    children,
    document.body // render into body, not parent
  );
}

Why Portals Exist

CSS properties like `overflow: hidden`, `z-index` stacking contexts, and `transform` on a parent can clip or hide child elements. Portals escape these constraints by attaching the rendered output to a different DOM node.

Event Bubbling Still Works

Even though the portal's DOM node is outside the parent, **React events still bubble** through the React component tree — not the DOM tree. A click inside a portal modal will bubble up to its React parent.

Creating a Portal Target

You can portal into any existing DOM node. A common pattern is to add a dedicated `
// index.html
<body>
  <div id="root"></div>
  <div id="modal-root"></div>
</body>

// Modal.jsx
createPortal(children, document.getElementById('modal-root'));

Portal Lifecycle Is Tied to Its React Parent

A portal mounts when its parent component mounts and unmounts when the parent unmounts. React still tracks it as part of the same component tree, so context and refs work normally.

Context Works Across Portals

Because portals remain part of the React component tree, context values provided above the portal are still accessible inside the portal. The DOM position does not affect the React context chain.

Using createPortal with State

Control portal visibility with a state variable. Toggle it with a button and the portal content appears in document.body while the button stays in its normal DOM position.
function App() {
  const [open, setOpen] = useState(false);
  return (
    <div>
      <button onClick={() => setOpen(true)}>Open</button>
      {open && createPortal(
        <div className="overlay">
          <button onClick={() => setOpen(false)}>Close</button>
        </div>,
        document.body
      )}
    </div>
  );
}

Server-Side Rendering & Portals

Portals require a DOM node to exist, so they are always client-side. In Next.js or other SSR setups, make sure the portal render code runs only in the browser using `useEffect` or a mounted state check.

Quick Check

React Portals render content into a different DOM node. What aspect of the React component tree is affected by this?

Recap

Portals let you render React output into any DOM node using createPortal(). The React tree, context, and event bubbling are unaffected. Use them to escape overflow/z-index constraints for modals and tooltips.

Up Next

Next lesson: **Building a Modal Component with Portals** — you will build a fully reusable modal that portals into document.body with open/close state management.

Frequently asked questions

Is the “What Are React Portals?” lesson free?

Yes — the full text of “What Are React Portals?” is free to read here on the web, and the React Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the React Academy course, upgrade to CoddyKit PRO.

What will I learn in “What Are React Portals?”?

Understand the createPortal API and why rendering outside the root div is useful. You practise React Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start React Academy?

No prior experience is required. React Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “What Are React Portals?” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this React Academy lesson?

Yes. Every React Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. What Are React Portals?
  2. Building a Modal Component with Portals
  3. Handling Focus & Keyboard Traps in Modals
  4. Tooltips & Dropdown Menus with Portals
← Back to React Academy