Portal
Rendering an element into a different part of the document than its logical parent.
A portal renders a component's output into a different location in the Document Object Model than its position in the component tree — usually at the end of the document body. Overlays use it: dialogs, popovers, tooltips, dropdown menus.
The reason is containment. An overlay rendered inside its logical parent inherits that parent's clipping, transforms, and stacking context, any of which can crop or mislayer it. Escaping to the body sidesteps all of them.
The escape is exactly what creates the difficulties.
Scoped styling breaks. Custom properties defined under a selector on an ancestor are not inherited by a portalled element, so any rule depending on them resolves to nothing — silently. The fix is to re-apply the scope marker on the portalled element itself; see Scoped Styling and CSS Custom Property.
Layering must be reasoned about globally. The portalled element joins the body's Stacking Context, where it competes with every other overlay and any fixed chrome.
Tests must query the right root. A test helper scoped to a component's own container will not find portalled content, because the content is not in that container — a failure that looks like a library bug and reproduces only under test.
Accessibility also needs explicit work, since the visual position and the tree position disagree; see Focus Management and ARIA.
See also4
Hand-picked in the note itself — the neighbours worth reading next.
Stacking Context
The nested coordinate system that decides what paints above what, and why z-index often does nothing.
Design & Interface12 connections
Headless Component
A component supplying behaviour and accessibility with no styling of its own.
Design & Interface13 connections
Focus Trap
Confining keyboard focus inside a modal surface so it cannot wander behind it.
Design & Interface10 connections
Component Story
An isolated rendered instance of a component, usable as documentation, a workbench, and a test.
Testing & Verification15 connections
Linked from14
Notes elsewhere in the wiki that reach for this one.
- AccessibilityDesign & Interface
Designing so that people with disabilities can use a thing, and the standards that make it checkable.
- ARIADesign & Interface
Attributes that describe roles, states, and relationships to assistive technology when HTML cannot.
- CascadeDesign & Interface
The algorithm deciding which declaration wins when several apply to the same element.
- Component StoryTesting & Verification
An isolated rendered instance of a component, usable as documentation, a workbench, and a test.
- contenteditableWeb Platform
The HTML attribute that makes an element directly editable, and the surface behind most rich-text editors.
- CSS Custom PropertyDesign & Interface
A user-defined CSS property that participates in the cascade and inherits down the tree.
- Dark ModeDesign & Interface
Serving an alternate palette for low-light preference, and the three states that implies.
- Document Object ModelWeb Platform
The live tree of objects a browser builds from a document, and the surface every UI framework writes to.
- Focus ManagementDesign & Interface
Deliberately controlling which element receives keyboard focus as an interface changes.
- Focus TrapDesign & Interface
Confining keyboard focus inside a modal surface so it cannot wander behind it.
- Headless ComponentDesign & Interface
A component supplying behaviour and accessibility with no styling of its own.
- Keyboard NavigationDesign & Interface
Making every interactive affordance reachable and operable without a pointer.
- Scoped StylingDesign & Interface
Confining a set of style decisions to a subtree so the same component can look different in different contexts.
- Stacking ContextDesign & Interface
The nested coordinate system that decides what paints above what, and why z-index often does nothing.