Portal — Stimeo UI

← All components

Moves an element elsewhere on the page, typically directly under the body. When an ancestor clips its content or creates a transform or stacking context, an overlay inside it cannot show properly; moving it out escapes that. A marker is left where it came from, so it can return to exactly the same place. On leaving you choose whether it goes back or is taken away, so no stray element is left behind. Where it went is reported as well. It does not compute placement or manage focus, so pair it with the positioning and dialog parts.

running

The card is moved under the body, so it escapes this clipped box and floats at the corner of the screen.

I'm rendered under <body> — outside the dashed box above.

Use case: lift tooltips, popovers, or modals out of an ancestor's overflow: hidden, z-index, or transform so they are not clipped or mis-stacked.

Keyboard

This component has no keyboard interactions of its own.

<%# Portal demo: the card is a content target, so on connect the controller teleports it
    out of the dashed (overflow:hidden) source box and into <body>, where demo.css floats
    it at the viewport corner — visibly escaping the clipping ancestor. demo.js reflects
    the mount destination into the status line. On disconnect (e.g. Turbo navigation) the
    card is restored, leaving no orphan. The library only moves the node and sets
    data-portaled; demo.css owns the look. %>
<div class="portal-demo">
  <div
    class="portal-demo__source"
    data-controller="stimeo--portal"
    data-stimeo--portal-to-value="body">
    <p class="portal-demo__hint"><%= t("components.portal.demo.hint") %></p>
    <div class="portal-demo__card" data-stimeo--portal-target="content">
      <%= t("components.portal.demo.card") %>
    </div>
  </div>
  <p
    class="portal-demo__status"
    role="status"
    data-portal-status
    data-mounted-label="<%= t("components.portal.demo.mounted") %>"></p>
  <p class="portal-demo__note"><%= t("components.portal.demo.note") %></p>
</div>

/*
 * Presentation-only styles for the portal demo. The library moves the card to <body>
 * and sets data-portaled; this CSS clips the source box (to show the card escaping it)
 * and floats the teleported card at the viewport corner.
 */

.portal-demo {
  display: flex;
  flex-direction: column;
  gap: 0.75rem;
  max-width: 28rem;
}

.portal-demo__source {
  padding: 1rem;
  border: 1px dashed var(--border);
  border-radius: 0.5rem;
  overflow: hidden;
}

.portal-demo__hint {
  margin: 0;
  color: var(--color-text-muted);
}

/* Teleported to <body>: pinned to the viewport corner, out of the clipped box. */
.portal-demo__card {
  position: fixed;
  right: 1rem;
  bottom: 1rem;
  z-index: 50;
  max-width: 16rem;
  padding: 0.75rem 1rem;
  border-radius: 0.5rem;
  background: var(--color-text);
  color: var(--surface-page);
  box-shadow: 0 10px 25px rgba(15, 23, 42, 0.25);
}

.portal-demo__status {
  margin: 0;
  color: var(--color-text-muted);
  font-variant-numeric: tabular-nums;
}

.portal-demo__note {
  margin: 0;
  font-size: 0.85rem;
  color: var(--color-text-muted);
}

// Portal demo (consumer-side JS).
//
// The controller teleports the card to <body> on connect; this JS only reflects where it
// landed into a status line. It both listens for the mount event and, in case connect
// already fired before this module ran, reports the current state once on load.
document.querySelectorAll(".portal-demo").forEach((root) => {
  const status = root.querySelector("[data-portal-status]");
  const source = root.querySelector('[data-controller="stimeo--portal"]');
  if (!status || !source) return;

  const label = status.dataset.mountedLabel ?? "Mounted into";
  const report = (target) => {
    status.textContent = `${label} <${(target?.tagName ?? "body").toLowerCase()}>`;
  };

  source.addEventListener("stimeo--portal:mount", (event) => report(event.detail.target));

  // If the content has already left the source, the mount event fired before this ran.
  if (!source.querySelector('[data-stimeo--portal-target="content"]')) {
    report(document.body);
  }
});

These demo styles use shared design tokens (light + dark). Copy the shared styles too, then toggle data-theme on your root element for dark mode.

The data-* attributes you add to your own HTML to wire this component. Put the data-controller below on a root element, then place its targets / values / actions inside that element.

On the root element data-controller="stimeo--portal"

Targets

Name	Description	Attribute
`content`	Optional node to move; defaults to the controller element when absent.	`data-stimeo--portal-target="content"`

Values

Name	Description	Attribute
`to`	CSS selector for the destination (default `body`). A declaration the engine cannot read — malformed or empty — falls back to the default; a well-formed selector that matches nothing moves nothing.	`data-stimeo--portal-to-value`
`position`	`append` (end) or `prepend` (start) within the destination (default `append`).	`data-stimeo--portal-position-value`
`restore`	Return the node to its original spot on disconnect, else remove it (default `true`).	`data-stimeo--portal-restore-value`

Events

Name	Description	Event
`mount`	Fires after the node is inserted into the destination, with `detail.target`.	`stimeo--portal:mount`
`unmount`	Fires when the node is restored / removed.	`stimeo--portal:unmount`

State hooks

The library only manages these ARIA/data attributes and custom properties. Your CSS reads them to render the look — selectors like [aria-selected], [aria-expanded], or var(--stimeo--…) hook into this state.

Hook	Target	Meaning
`data-portaled`	The moved node	Present (true) while the node is teleported.