Skip to content
Domphy

Portal

_portal redirects where an element's DOM renders — the element stays in the logical Domphy tree, but its DOM node is appended to a different parent.

{
  div: "Tooltip content",
  _portal: (root) => document.body,
}

root is the app root ElementNode. Use it to query or insert overlay containers:

{
  div: "...",
  _portal: (root) => {
    let overlay = root.domElement!.querySelector("#my-overlay")
    if (!overlay) {
      overlay = document.createElement("div")
      overlay.id = "my-overlay"
      root.domElement!.appendChild(overlay)
    }
    return overlay
  },
}

Why Use Portals

Without _portal, fixed or absolute overlays inherit overflow: hidden and stacking context from ancestor elements, which causes clipping and layering bugs.

Properties

  • The element's logic remains tied to its position in the Domphy tree
  • Only the DOM node moves
  • CSS generated by the element is still injected normally
  • _portal is evaluated once at mount time

Use it for overlays that must escape ancestor layout constraints: tooltips, dropdowns, toasts, and modal layers.