Full spec

A zero-JS, HTML-first constraint layout engine mapping CSS Anchor Positioning to an iOS Auto Layout-style DOM API.

tests/ has a live, runnable version of everything below — one demo+test HTML file per feature, viewable directly in a browser or checked headlessly via npm test. Treat it as the executable source of truth for what actually works, not just this document.

Editor autocomplete: anchored-auto-layout.html-data.json describes every data-⚓️-* attribute (with value suggestions where applicable) in VS Code's HTML custom data format. Point your project's .vscode/settings.json at it:

{ "html.customData": ["./node_modules/anchored-auto-layout/anchored-auto-layout.html-data.json"] }

(This repo's own .vscode/settings.json already wires it up locally.)

Core Principles

• Relational & Extrinsic: Position relative to any element, breaking strict DOM hierarchy.
• Zero-JS Execution: Math, collisions, and visibility handled entirely by the browser's C++ engine.
• HTML-First & Distinct: Layout logic lives in markup. The data-⚓️-* namespace visually separates constraints from styling classes.
• i18n-Native: Driven by CSS logical properties for automatic RTL layout mirroring.

Syntax & Routing

• Explicit (Multi-Anchor): String values target specific anchors (e.g., data-⚓️-below="--header").
• Implicit (Boolean): Setting data-⚓️-to="--btn" allows modifiers to act as booleans (e.g., data-⚓️-below, data-⚓️-sync-width).

API Reference

Built-In Intelligence Layers

• Top-Layer Reset: Applying a target to <dialog> or [popover] natively strips the browser's aggressive User-Agent centering margins.
• Sub-Menu Contexts: Elements acting as both target and anchor automatically establish a pristine 3D containing block (preserve-3d) for nested dropdowns.
• Anchored Container Queries: Targets automatically inject container-type: anchored, allowing internal elements to restyle themselves based on fallback collision flips. Side effect worth knowing: like any non-normal container-type, this makes the target a containing block for position: fixed descendants too (confirmed live), not just a query container — a plain position: fixed element nested anywhere inside a target no longer pins to the true viewport, it pins to the target's own box instead. Site-wide consequence here: <main> is itself a target (data-⚓️-to="--header"), so any page content wanting real viewport-fixed UI (a floating action button, a toast) needs to render outside <main> — e.g. portaled to document.body — rather than relying on plain position: fixed from within page content. Found building the playground's mobile "Controls" FAB, which rendered ~200px below the visible viewport before the fix.
• Anchor Interpolated Morphing (AIM): Elements can animate their entry from perfectly collapsed inside an anchor's geometry (data-⚓️-morph-from) to their resolved layout, using native @starting-style — no JS FLIP technique required.

Trade-offs & Constraints

• Extrinsic Handling: Elements are position: absolute. Internal text overflow must be handled manually (overflow: auto).
• Unidirectional: Circular dependencies (A ↔ B) are ignored by the browser.
• Prefix Required: HTML string values must explicitly include double dashes (e.g., "--header").
• Same-Axis Sizing Conflicts: data-⚓️-stretch-[x|y] (implicit sizing via opposing insets) and data-⚓️-sync-[width|height] (explicit width/height) both resolve the same axis differently. Combine them on different axes freely (e.g. stretch-x + sync-height), but on the same axis the explicit width/height from sync-* wins over the stretch insets, per standard over-constrained absolute-positioning sizing rules — the stretch is silently dropped on that axis, not merged.

Browser Support

The library needs CSS Anchor Positioning and typed attr() (attr(data-⚓️-x type(<custom-ident>))), which is how every --name gets from markup into CSS. Without typed attr() the attributes are inert, so feature-detect that, not anchoring: @supports (anchor-name: attr(data-x type(<custom-ident>))).

Per feature (Chromium versions from the docsite's browser-support page; Firefox/Safari columns from MDN browser-compat-data, checked 2026-10-30, not verified by this library's tests):

Known Browser Limitations (verified live, not authoring bugs)

• Resolved — the "end-only inset" problem was the UA popover stylesheet, not a browser bug. [popover]/<dialog> get inset: 0 and fit-content sizing from the UA sheet, which over-constrains any box that sets only one inset (an inset-block-end: anchor(...) alone rendered at the wrong place). The top-layer reset (section 1) clears inset/width/height/margins inside :where(), so it has zero specificity and never beats an anchor()-driven longhand or an author class. above, before, align-bottom and align-trailing are therefore plain logical inset-block-end/inset-inline-end on every target type (an earlier translate workaround, --⚓️-tx/--⚓️-ty, was removed). Consequences: RTL and vertical writing modes work, native flip-block/flip-inline work on popovers in both directions (custom position-area flip blocks removed), and data-⚓️-stretch-[x|y] sizes popovers correctly. Trade-off: switching between a start attribute and an end one (below <-> above) changes which inset is used and inset cannot interpolate from auto, so that swap snaps instead of tweening; same-attribute changes and size still morph.
• anchor-valid (data-⚓️-visibility="valid") needs Chrome 157+. The CSSWG renamed anchors-visible/anchors-valid to singular anchor-visible/anchor-valid (blink-dev intents, Chrome 157, plurals kept as deprecated aliases). The old plural anchors-valid was never shippable (reverted over spec ambiguity), so in Chromium 153 CSS.supports("position-visibility", "anchors-valid") and the singular forms all return false, while plural anchors-visible, no-overflow and always work. The library declares plural then singular for every value (an engine drops the declaration it doesn't parse), so visible works everywhere and gains the singular spelling for free; any value including valid (valid, valid-no-overflow, all) silently falls back to the initial value until the engine supports anchor-valid. tests/10-visibility-state.html probes support with CSS.supports and only treats valid values as a known gap when neither spelling parses.
• data-⚓️-try measures overflow against the target's containing block and the scrollable area. Confirmed while testing: an extra position: absolute wrapper between a popover's anchor and the viewport, or a tall (scrollable) document, changes what counts as overflowing, so a box hanging off the bottom of the viewport can simply not flip. Anchors placed directly on a non-scrolling viewport (position: fixed) behave as expected (tests 09 and 16).
• position-try-fallbacks does not re-evaluate on scroll — confirmed live, current Chromium (153.0.8010.12). An anchor-positioned element (plain or [popover], root-document scroll or an overflow: auto scroll container, data-⚓️-try on any axis) picks its fallback exactly once — apparently checking overflow against the anchor's position as of scrollY: 0/initial layout, never the actual current scroll-adjusted viewport position. Verified 5 independent ways: scrolling an already-open popover into an overflowing position (no re-flip, holds for 4.5s+ across 15 polled frames); resizing the viewport instead of scrolling (same); closing and reopening a popover while already scrolled to an overflowing position (still no flip — rules out a stale/cached fallback choice, since this is a fresh showPopover() call); and inserting a brand-new DOM node (never laid out before) at an already-scrolled, already-overflowing position (still no flip — rules out any per-element caching entirely). A page scrolled via window.scrollTo() before the browser's first paint pass still doesn't get correct fallback selection either, which is what pins this down precisely: the algorithm isn't stale-caching a past result, it's not factoring scroll position into its overflow check at all, ever. This directly contradicts MDN's own description of the feature ("re-evaluates continuously as the user scrolls") — worth re-testing against a future Chromium release rather than assuming MDN is simply wrong. Practical impact: any UI built on the assumption that scrolling an anchor toward a viewport edge live-triggers its data-⚓️-try fallback (e.g. a tooltip that's expected to flip sides as its anchor scrolls near the top/bottom of the screen) will not work today — the fallback is only correctly chosen at the moment the element is first laid out (its very first style/layout pass, scrollY baked in at that instant), not on later scroll events. No workaround identified; this sits below the CSS layer entirely.
• Animating a fill across a reflow: data-⚓️-fill handles it, stretch-x + stretch-y don't. Confirmed live building the animated-grid-reflow demo (Bramus's technique of anchoring absolutely-positioned content to a grid cell so it can animate independently of the grid's own instant reflow): a box sized purely by 4 inset longhands (stretch-x + stretch-y), or by the inset: anchor(inside) shorthand with no explicit size, visibly collapses to ~0px wide partway through a transition: inset when its anchor moves, even though old and new size are identical. data-⚓️-fill therefore sets both the single inset: anchor(inside) shorthand and an explicit width/height from anchor-size(), which makes the size authoritative so only the position animates (verified sampling every frame: no collapse, in real Chrome). Chrome still reports four separate inset-* transitions for the shorthand, so why the shorthand plus explicit size works isn't established. Author width/height override the built-in ones.