Utilities
The render-elsewhere primitives. Portal moves children out of their place in the DOM; Overlay is a full-viewport scrim built on it.
The pieces
| Component | Use it for |
|---|---|
| Overlay | A full-viewport scrim — the backdrop for a modal. |
| Portal | Render children into a different part of the DOM. |
Escaping the hierarchy
Most components render where they are written. These two do not. A modal written deep inside a
card needs to cover the whole viewport — but an ancestor's overflow: hidden or transform
would clip or contain it. Portal solves that by rendering its children at document.body,
clear of every ancestor's clipping and stacking context. Overlay is a Portal plus a
fixed-position scrim, so the backdrop genuinely covers everything.
Building blocks, not finished surfaces
Neither component is a dialog. Overlay draws a scrim and reports a click on it — it does not
trap focus, handle Escape, or make the background inert. Portal only relocates children.
A complete modal composes these with FocusScope: Portal to escape
the hierarchy, Overlay for the scrim, FocusScope for the focus contract. That composition is
exactly what the headless Dialog does — reach for it when you want the finished surface, and for
these primitives when you are building your own.