Portal

<Portal> relocates its children to another DOM node — by default document.body, or a selector / element you pass as to. Use it when an ancestor's overflow, z-index, or transform would clip or bury UI that should float above the page: toasts, tooltips, menus, and custom overlays.

import { Portal } from "@opentf/web";

{open && (
  <Portal to="body">
    <div class="toast">Saved!</div>
  </Portal>
)}

On connect the runtime moves the portal's light-DOM children to the target; on unmount it removes them so custom-element disconnect and effect cleanups run. No manual DOM bookkeeping.

Open the portaled modal inside the clipped box — it renders on document.body, not inside the clip region. Compare with the native <dialog> below the demo.

The to target

<Portal to="#toast-root">
  <p>Rendered into the element with id="toast-root".</p>
</Portal>

Portals vs native <dialog>

For modals and dialogs, the browser top layer is often simpler — no relocation, free backdrop, Esc-to-close:

const dialogRef = $ref();

<button onclick={() => dialogRef.showModal()}>Open</button>
<dialog ref={dialogRef}>
  <p>Native top layer</p>
  <button onclick={() => dialogRef.close()}>Close</button>
</dialog>

Reach for <Portal> when you need a general escape hatch — stacked toasts, custom overlays, tooltips anchored to arbitrary targets, or markup that does not map cleanly to <dialog>.

Runtime API

Also listed on the Runtime API reference.

Related

• Context — portaled subtrees still resolve $context from the logical tree.

• Error boundaries — throws inside portaled content route to the nearest boundary.

• Components — where portals fit in the tree.

• Imperative API — $ref for native <dialog>.