docs / portals

Portals and layering

Choose the sheet rendering boundary deliberately for pages, shells, and embedded surfaces.

Use the document boundary by default

Sheet.Portal renders into the document body by default so application layout, overflow, and stacking contexts do not accidentally clip a modal sheet. This is the right boundary for most page-level workflows.

Own an embedded surface

Pass a concrete container when the sheet belongs inside a phone preview, editor canvas, or isolated application shell. The container must establish the size and clipping boundary that Sheet.Viewport should fill.

const [container, setContainer] = useState<HTMLDivElement | null>(null)

return (
  <div ref={setContainer}>
    <Sheet.Portal container={container}>…</Sheet.Portal>
  </div>
)

Treat z-index as a system

A large z-index cannot escape an ancestor stacking context. Keep overlays in a documented application layer and inspect transformed, isolated, positioned, or opacity-adjusted ancestors when a sheet appears underneath unrelated UI.