When a component renders a subtree through a portal, what changes about that subtree and what stays the same?

Most of the time a component's output lands inside its parent's output, and the two trees — the component tree you wrote and the host tree the framework built — have the same shape. A **portal** deliberately breaks that correspondence for one subtree: the output is attached to a host container you nominate, while the subtree's position in the component tree is untouched. ## Why overlays need it at all An overlay's box is not free to be wherever it likes. Ancestors constrain it: - an ancestor that clips its overflow cuts off anything that extends past its box; - an ancestor that establishes a containing block or its own stacking context confines where the panel can be positioned and how it orders against other content; - an ancestor with its own transform changes the coordinate space the panel positions itself in. None of that can be styled away from inside, because the constraint belongs to the ancestor. Attaching the output near the root, where no such ancestor sits above it, is the mechanism that actually works. (The details of stacking contexts and compositing are the host platform's own subject.) ## The two halves, precisely | Aspect | Where it follows after portalling | | --- | --- | | Host output location | the nominated container | | Position in the component tree | unchanged — still under the rendering parent | | Ancestor-provided values | resolved up the component tree, as before | | State and identity of the subtree | owned by the same parent instance, preserved across updates | | Teardown | with the rendering parent, not with the container | | Framework-level event propagation | the component tree, in runtimes with their own dispatch | | Host-native propagation and reading order | the new host location | The first line is the only thing a portal changes about your model. The last line is where all the surprises come from. ## The costs you inherit 1. **Containment tests stop matching.** Code that asks "is the thing that was interacted with inside my node?" — the usual dismiss-on-outside-interaction check — now answers no for the panel's own content, because that content is not inside the trigger's node any more. The fix is to test membership against both roots, or against the component-level relationship the runtime can tell you about, rather than one node's subtree. 2. **Two propagation stories.** A runtime with its own event dispatch propagates along the component tree, so a handler on the rendering parent still sees interactions inside the portalled panel even though no host ancestry connects them. A runtime that leans on the host's own bubbling sees the events travel from the new location instead. Know which your runtime does before you reason about a handler that "should not" have fired — the host's propagation rules themselves are the platform's subject, not the framework's. 3. **Order changed for anyone reading linearly.** The output now sits near the root, far from the control that opened it, which changes the sequence assistive technology and sequential navigation traverse. Overlays therefore need explicit attention to where attention goes and where it returns — that discipline is an accessibility subject with its own rules, but the portal is what created the gap. 4. **Someone must own the container.** A per-component container created ad hoc multiplies roots and makes the ordering between two overlays accidental. One owned layer, created once, is the version that behaves predictably when a dialog opens a tooltip. ## What a portal does not do It is worth being blunt about the non-effects, because they are the most common misconceptions: - it does not give the subtree different ancestors, so it cannot be used to "escape" an ancestor-provided value; - it does not make the subtree an independent root with its own state or its own teardown schedule; - it does not solve a layout problem that is really inside the parent's own box — if nothing above is clipping or containing you, ordinary positioning is the simpler answer; - it does not relieve the rendering parent of cleanup: when the parent goes, the portalled output goes with it. ## How runtimes vary The shape of the feature differs — a wrapper element in the description, a directive on an element, an imperative call — and so does what happens when you *change* the target container: some runtimes move the existing host output, others re-create it there, which matters if the subtree holds host state such as scroll position or a text selection. What is common across them is the contract in the table above: one tree is re-pointed, the other is not.