[FEE-11001] CSS Anchor Positioning
INFO
Tether any floating overlay — tooltip, dropdown, popover — to any element on the page using pure CSS, with automatic overflow repositioning and no JavaScript required.
Baseline Newly Available
Supported in Chrome 125+, Firefox 130+, Safari 18.4+. Use progressive enhancement for older browsers.
Context
Every developer who has built a tooltip, dropdown menu, or context menu has run into the same wall: CSS position: absolute offsets an element relative to its nearest positioned ancestor, not relative to an arbitrary sibling or cousin element in the DOM tree. The anchor element and the floating overlay frequently live in different stacking contexts, different scroll containers, or simply at different nesting depths.
The traditional workaround is JavaScript:
- Read the anchor element's position with
getBoundingClientRect(). - Calculate where the overlay should go.
- Set
topandleftimperatively. - Wire up
ResizeObserverand scroll listeners to keep everything in sync. - Repeat all of this on every resize and orientation change.
Libraries like Popper.js and Floating UI have solved this problem reliably for years, but they add kilobytes, require JavaScript to be parsed and executed before the UI is correct, and can produce a brief flash of mispositioned content (FOMC) during the first paint before the layout calculations run.
CSS Anchor Positioning moves all of this work into the browser's layout engine. The browser computes anchor positions during the same layout pass that handles everything else — before paint, not after. No ResizeObserver loops. No scroll listeners. No JavaScript at all for the positioning itself.
Scenario
You are building a "Copy to clipboard" button inside a code block. When the user clicks it, a small "Copied!" tooltip should appear above the button. If the button is near the top of the viewport, the tooltip should automatically flip below the button instead of overflowing off-screen. The tooltip is powered by the Popover API for accessibility.
With traditional CSS you would need JavaScript to measure the button's position and write top/left styles imperatively. With CSS Anchor Positioning, the entire positioning relationship — including the overflow fallback — is declared in CSS.
Best Practices
- MUST define
position-try-fallbacksfor any anchor-positioned element that could appear near screen edges. Without fallbacks, the overlay clips or overflows the viewport. - SHOULD combine CSS Anchor Positioning with the Popover API to get accessible focus management and keyboard dismissal for free, without extra JavaScript.
- MUST NOT use CSS Anchor Positioning for document layout — block elements, grid tracks, or page structure. The feature is designed exclusively for floating overlays that sit above the normal flow.
- Use
anchor-nameon the interactive element that triggers the overlay (the button, link, or input), not on a wrapper<div>. This keeps the anchor semantically tied to the element users interact with. - MUST apply progressive enhancement. Wrap anchor positioning properties in a
@supports (anchor-name: --x)block so older browsers fall back to a static or JS-driven position rather than a broken layout. - In lists or repeated components, use
anchor-scopeto preventanchor-namevalues from leaking across list items and accidentally targeting the wrong anchor.
Design Thinking
Why JavaScript was required
position: absolute in CSS resolves offsets against the element's containing block, which is the nearest ancestor with a position other than static (or the initial containing block for the viewport). There is no CSS mechanism to say "offset relative to this specific sibling element" — CSS has never had a cross-element reference mechanism for geometry until now.
When position: absolute is not enough, developers have two traditional options:
- Restructure the DOM so the overlay is a child of the anchor. This breaks if the anchor lives inside
overflow: hidden, a CSStransform, or awill-changecontext — all of which create new stacking and containing-block contexts. - JavaScript measurement via
getBoundingClientRect(), which works but requires runtime recalculation on every scroll, resize, and orientation change.
How Popper.js and Floating UI solved it
Both libraries follow the same pattern: on open, read the anchor's DOMRect, do geometry math, set position: fixed or position: absolute with calculated top/left. They use ResizeObserver to detect size changes and passive scroll listeners to recompute on scroll. The result is correct positioning, but at the cost of a synchronization loop between JavaScript and the browser's layout engine.
The flash of mispositioned content happens because JavaScript runs after the browser has already painted. The element first renders at its default position, then JavaScript moves it, and then the browser repaints.
Why native CSS is better
CSS Anchor Positioning runs inside the browser's layout engine, in the same pass that resolves all other geometry. This means:
- No FOMC: The positioned element is placed correctly before the first paint.
- No ResizeObserver: The browser already tracks element sizes as part of layout — there is no need for a separate JavaScript observation loop.
- Automatic scroll tracking: Anchor-positioned elements follow their anchor through scrolling without any
scrollevent listener. - Declarative overflow handling:
position-try-fallbacksencodes all alternative positions in CSS. The browser picks the best fit automatically.
The tradeoff is that CSS Anchor Positioning only works for elements that can be position: absolute or position: fixed — it does not apply to elements in normal flow.
Example
A "Copy" button with a tooltip that appears above and automatically repositions to below when the button is near the top edge of the viewport.
<div class="code-block">
<pre><code>const x = 1;</code></pre>
<button class="copy-btn" id="copy-btn" popovertarget="copy-tooltip">
Copy
</button>
<div id="copy-tooltip" class="tooltip" popover>Copied!</div>
</div>/* Fallback for unsupported browsers */
.tooltip {
position: fixed;
top: 50%;
left: 50%;
transform: translate(-50%, -50%);
}
/* Anchor positioning where supported */
@supports (anchor-name: --x) {
.copy-btn {
anchor-name: --copy-btn;
}
.tooltip {
position: absolute;
position-anchor: --copy-btn;
position-area: top center;
position-try-fallbacks: flip-block;
margin: 8px;
/* reset the fallback fixed positioning */
top: unset;
left: unset;
transform: none;
}
}What this does
- The
popovertarget="copy-tooltip"attribute on the invoker button, combined withid="copy-btn"on the button itself, is what lets the browser resolve the implicit anchor relationship — theposition-anchorproperty in CSS can reference this without repeating the CSSanchor-name. position-area: top centerplaces the tooltip above the button, horizontally centered.position-try-fallbacks: flip-blocktells the browser: if the preferred position overflows the viewport, try the mirrored position in the block axis (i.e., switch from top to bottom or vice versa). For more complex multi-step fallbacks, define a named@position-tryblock.- The
@supports (anchor-name: --x)block uses the positive form recommended in Best Practices, applying anchor positioning only where supported while the fallback fixed positioning outside the block handles older browsers.
Deep Dive
The inset-area rename
Early drafts and Chrome versions 125–128 used the property name inset-area. The CSS Working Group renamed it to position-area in Chrome 129 (shipped). If you encounter inset-area in older documentation or tutorials, treat it as the same property. Both names referred to the same grid-based positioning shorthand; position-area is the canonical name.
Similarly, position-try-options was an earlier name for position-try-fallbacks. Only position-try-fallbacks is current.
The anchor() function
For precise edge-to-edge positioning, use the anchor() function instead of position-area:
.tooltip {
position: absolute;
position-anchor: --copy-btn;
/* Left edge of tooltip = right edge of anchor */
left: anchor(right);
/* Top edge of tooltip = bottom edge of anchor */
top: anchor(bottom);
}anchor() takes a side keyword: top, right, bottom, left, start, end, self-start, self-end, center, or a percentage. This gives you pixel-perfect control over which edge of the positioned element aligns to which edge of the anchor.
The anchor-size() function
To size the overlay relative to the anchor:
.dropdown {
position: absolute;
position-anchor: --trigger;
/* Match the anchor's width exactly */
width: anchor-size(width);
/* Or cap at the anchor's width */
max-width: anchor-size(width);
}anchor-size() accepts width, height, block, inline, self-block, or self-inline.
Named fallback rules with @position-try
For complex fallbacks that involve more than just a different position-area, use @position-try to define named rule sets:
@position-try --flip-below {
position-area: bottom center;
margin-top: 8px;
margin-bottom: 0;
}
@position-try --flip-right {
position-area: right span-top;
margin-left: 8px;
}
.tooltip {
position: absolute;
position-anchor: --copy-btn;
position-area: top center;
margin-bottom: 8px;
/* Try named fallbacks in order */
position-try-fallbacks: --flip-below, --flip-right;
}The browser tries each fallback in order and uses the first one where the positioned element fits entirely within its scroll container.
The implicit anchor
If the popover is associated with its invoker via popovertarget / id attributes, the invoker automatically becomes the popover's implicit anchor. In that case, position-anchor in CSS can be omitted:
/* This works when the HTML anchor association is in place */
.tooltip {
position: absolute;
position-area: top center;
position-try-fallbacks: flip-block;
}The explicit position-anchor declaration is still recommended for clarity, especially when the CSS is read in isolation.
Interaction with overflow: hidden
Anchor positioning resolves against the scroll container that contains the anchor, not the CSS containing block. This means an overlay can escape a parent with overflow: hidden if that parent is not a scroll container. However, the overlay is still clipped if it leaves the nearest scroll container — it does not escape to the viewport automatically unless it uses position: fixed.
For tooltips that must escape all overflow constraints, use position: fixed combined with anchor positioning. position: fixed makes the scroll container the viewport, and anchor positioning still works correctly.
anchor-scope
In lists or repeated components, multiple elements may share the same anchor-name value. By default, a positioned element finds the last anchor with the matching name in DOM order, which is almost never what you want in a list.
anchor-scope limits which positioned elements can reference a given anchor-name, scoped to a subtree:
.list-item {
/* Scoped so anchors in this item only match popovers inside this item */
anchor-scope: --item-anchor;
}
.list-item .trigger {
anchor-name: --item-anchor;
}
.list-item .menu {
position: absolute;
position-anchor: --item-anchor;
position-area: bottom span-right;
}anchor-scope accepts either a single <dashed-ident> or the keyword all. Using all scopes every anchor-name declared in the subtree, which is a convenient blanket guard for complex component trees where many anchors are defined.
Note that anchor-scope only affects name resolution — it does not affect overflow or containment behavior.
Common Mistakes
Forgetting position-try-fallbacks near viewport edges. An anchor-positioned tooltip with no fallback will overflow or be clipped when the anchor is near the top, bottom, left, or right edge of the viewport. Always declare at least position-try-fallbacks: flip-block for vertically-placed overlays, or flip-inline for horizontally-placed ones.
Using anchor-name on a wrapper <div> instead of the interactive element. Screen readers and keyboard navigation expect the interactive element (button, link, input) to carry the accessible relationship to its overlay. Putting anchor-name on a non-interactive ancestor severs this relationship.
Using CSS Anchor Positioning for normal-flow layout. Properties like position-area and anchor() only affect elements that are position: absolute or position: fixed. Applying them to block-level elements in normal flow has no effect and misleads readers of the CSS.
Assuming position: fixed is required to escape overflow: hidden.position: fixed works, but it also removes the element from its scroll container's coordinate system, which can cause the overlay to not follow the anchor when the page scrolls. Prefer position: absolute unless you specifically need viewport-relative positioning; check whether the overflow: hidden ancestor is a scroll container first — if it is not, position: absolute will already escape it.
Omitting @supports wrapping. Without feature detection, anchor positioning properties are silently ignored in older browsers — but any fallback styles you intended to apply outside the @supports block may also be overridden by properties inside it if you forget to reset them. Always pair the anchor positioning block with a fallback outside it.
Browser Support
| Browser | First version | Notes |
|---|---|---|
| Chrome | 125 | Interop 2025 participant |
| Firefox | 130 | |
| Safari | 18.4 | |
| Edge | 125 | Chromium-based |
Progressive enhancement pattern using @supports:
@supports (anchor-name: --x) {
/* Anchor positioning styles */
}Or in JavaScript for feature-gating overlay libraries:
const supportsAnchorPositioning =
CSS.supports('anchor-name', '--x');Internal References
- FEE-11002 Container Queries — Both anchor positioning and container queries use containment concepts: anchor positioning scopes name resolution to subtrees via
anchor-scope, while container queries scope style evaluation to a container subtree. - FEE-11101 @starting-style —
@starting-styleis frequently combined with anchor-positioned popovers to animate the overlay's entry transition (e.g., fade in from the anchor direction) without JavaScript.