layout-measurement-strategy
Measure and trust the intrinsic or auto layout size of a DOM element. Use when offsetHeight, getBoundingClientRect, ResizeObserver, scrollHeight, or a mirror, clone, or probe returns zero, border-only
SKILL.mdskills/layout-measurement-strategy/SKILL.md
GitHubLayout Measurement Strategy
The one theorem everything follows from
A layout size is not a property of an element. It is the output of a function whose inputs are (1) the real inline size the element is resolved against, (2) the full CSS context imposed by its ancestors and formatting context, and (3) the readiness of its content. Pin all three to their real-render values or you have measured a different function, not the same element more cleanly.
Auto block-size (height, in horizontal writing modes) is a function of inline-size (width): text wraps, container queries flip, flex/grid constraints resolve — all against the available inline size. Change the width, the context, or read before content is ready, and the number is confidently wrong.
The trap that makes this hard: the browser never signals that a layout is provisional. There is no isLayoutFinal flag. An early or mis-contexted read returns a plausible-but-wrong number silently — which is worse than an error, because downstream code commits it.
The two failure modes (90% of real bugs)
- No box / collapsed box.
display: nonegenerates no layout box (measures0). Or the element is in flow but its content hasn't expanded it yet, so it's onlyborder-top + border-bottomtall — the border-only read (1–2px). This is the collapsed-widget bug below. - Wrong constraint. Measured at a different width, missing CSS variables/fonts/ancestor classes, or moved to a different parent (
document.body) where the cascade and formatting context differ.
The mindset shift: from "measure now" to "observe and settle"
Do not ask "when is the right instant to read the size?" — you will guess wrong, because content arrives late (fonts swap, images load, async children stream). Instead:
- Producer: subscribe with a
ResizeObserverand take the settled value. RO fires after layout, before paint, and re-fires on every change — first layout, font swap, image load, stream chunk. It turns "is the geometry final?" from a guess into an event. - Consumer: apply a reject-border-only guard (below). Even a correct producer gets its value grabbed early by some eager consumer. The consumer must refuse a collapsed number, not assume what it received is real.
The border-only failure is defeated only by both halves — waiting for the real value and refusing to commit the collapsed one.
Before you measure: can the layout engine do it?
The cheapest measurement is the one you never take. If the browser can size or position the thing for you — a corner badge with position: absolute; top/right (needs no height at all), content-driven height with CSS grid/flex, space reserved with aspect-ratio or contain-intrinsic-size — do that instead of reading geometry into JS. Every measured number is at least one frame stale and becomes its own bug surface (the collapse, the font/image race, the re-render lag). Reach for measurement only when a value genuinely has to cross into JS to drive something the layout engine can't express.
Decision spine
- In the DOM, not
display: none.visibility: hiddenandposition: absolutekeep the layout box (they still lay out);display: nonehas none. Detect it:el.offsetParent === nulloroffsetHeight === 0. - Fix the real inline size; read the block size. Height is a function of width. Think logical axes (
inline-size/block-size), not physical width/height, so RTL and vertical writing modes don't silently measure the wrong axis. - Default to in-place or portal-in-subtree. Off-flow is the exception. In-place measurement replicates nothing because nothing moved — it keeps the containing block, formatting context, query container, inherited vars, and shadow stylesheets. Reach for off-flow only when the size is genuinely content-driven and you need the number synchronously before paint.
- If off-flow: replicate context, don't copy computed styles. Reproduce the ancestor chain, not a snapshot of resolved lengths (copying
getComputedStylefreezes%,em,ch,fit-content, and kills container queries). - Reject border-only / collapsed measurements. A content-bearing element measuring to ~chrome height means layout hasn't happened yet, not height is 0. Never feed it to badges, radii, insets, or animations.
- Cooperate for lists/previews: measure once, cache, feed it back.
content-visibility: auto+contain-intrinsic-size: auto <last-size>lets the browser hold the space and self-correct — instead of re-measuring on every reveal or betting a fixed placeholder height.
Why "height: 0" and "append to body" are the wrong defaults
height: 0on the element you're measuring — underoverflow: hidden, flex/grid, or percentage-height parents, you read back the constrained0, not the intrinsic size. Keep the measured elementheight: auto; move a placeholder to control flow, not the content.- Appending the probe to
document.body— silently drops CSS custom properties (the most common thing to revert), ancestor classes that drive descendant selectors (.dark,[data-density],:has()), the@containerquery context, and any shadow-rootadoptedStyleSheets. You measured a different element than the one you'll render.
What corrupts a naive off-flow measurement (the CSS mechanisms)
The cases where measurement is hardest are exactly the cases where the real layout, not the element, owns the size — so there is no clean intrinsic number to extract off-flow:
- Percentage / flex-basis heights resolve against a definite containing block. Off-flow under an
auto-height wrapper, they resolve toauto→ different number. Strongest argument for in-place. - Flex/grid children carry
min-height: auto(won't shrink below min-content unless you setmin-height: 0) and, withalign-items: stretch(default), are stretched to the line's cross size — so you measure the container, not the item. Off-flow removes the stretch, giving content size. Neither is "wrong"; name which one you want. This is the collapsed-widget mechanism. aspect-ratiomakes block-size a function of resolved inline-size — unmeasurable before width is final.contain: size/content-visibilitymake size independent of contents by contract → measures0(orcontain-intrinsic-size).content-visibility: autoskips layout while off-screen — putting a probe off-screen defeats itself. Check ancestors for these.- Container queries resolve against the nearest
container-typeancestor's inline size. Off-flow, that container is gone or wrong-sized → styles flip → wrong height. To measure off-flow you must reproduce[container @ real inline-size] > [node]and keep the width in sync — at which point in-place is cheaper and correct.
Full context-replication travel list and the container-query / shadow-DOM details are in references/context-replication.md.
Choosing the measurement API
| Need | Use | Notes |
|---|---|---|
| "Notify me when the real size settles" (fonts/images/stream) | ResizeObserver (borderBoxSize[0].blockSize) |
Fires after layout, before paint; re-fires on every change; hands you the value without forcing a reflow. The default for auto-height. |
| Fractional visual size, no transforms in the chain | getBoundingClientRect().height |
Sub-pixel float; includes transforms (a scale(0.5) reports half). Forces a sync reflow. |
| Transform-immune integer layout size | offsetHeight / offsetWidth |
Ignores transforms; rounds to integer (don't sum many). Border-box. 0 ⇒ display:none. |
| Learn the CSS context to replicate | getComputedStyle() |
Use for non-geometric facts (font, custom props). Also forces a reflow for layout props — not free. |
Box consistency: getBoundingClientRect / offset* are border-box; contentRect / clientWidth are content-box. Pick one box and stay in it end-to-end. When feeding a measured height back into layout, Math.ceil it — a rounded-down height crops the last text line.
Margins are in none of these boxes, and a child's top/bottom margin can collapse through an auto-height wrapper — so the measured box comes back short by the collapsed margin. Give the measured wrapper its own block formatting context (display: flow-root) so child margins stay inside the number, or measure an element you know establishes a BFC.
Timing
| Situation | Primitive | Why |
|---|---|---|
| Height depends only on a width you set; content already in DOM; no web fonts/images | Forced reflow: write width → read offsetHeight in the same task |
The read's synchronous flush honors the pending write. Deterministic, no frame wait. |
| Just inserted / unhid synchronously; want the settled box | one ResizeObserver callback (preferred) or double-rAF |
Give the engine a committed layout pass. RO waits for the actual event; double-rAF waits a fixed 2 frames that may be too short (async content on frame 3) or wasteful. |
| Text with web fonts | await document.fonts.ready before trusting |
Fallback metrics give shorter, provisional line boxes. |
| Images / replaced content contribute to height | await img.decode() / load, or let RO catch the reflow |
0 intrinsic size until the resource resolves. |
| Measuring N nodes | Batch: all writes, then all reads | One forced layout total vs O(N). Never issue a layout-dirtying write between reads. |
| Feeds a visible size change | useLayoutEffect / RO, not useEffect |
Runs after commit, before paint → no flash of the un-sized state. |
The reject-border-only guard
A measurement pipeline needs a validity predicate, not just a value. All the early-read failure modes collapse the number toward border-only/zero, so a lower-bound plausibility check catches them:
// content-box contribution ≈ 0 while the element HAS content ⇒ layout hasn't
// happened yet. Treat as "not measured," not "height is 0."
function isTrustworthy(borderBoxH: number, chromeH: number, prev?: number): boolean {
if (!Number.isFinite(borderBoxH) || borderBoxH <= 0) return false;
if (borderBoxH - chromeH <= 1) return false; // border-only
if (prev != null && borderBoxH < prev * 0.25) return false; // implausible collapse
return true;
}
Commit a value only when it passes the predicate and is stable across two consecutive RO deliveries (RO fires on every reflow, so stability-across-two is the practical "settled" signal). Then disconnect the observer.
Case study — a collapsed widget preview
The widget body is a flex/grid child. The host chrome laid out first and resolved the row before the body had content to contribute, so the auto-height body collapsed to border-top + border-bottom (~1–2px). The preview read that 1–2px as "the height" and drew the Stage badge against a ~0-height box — the badge detached from its corner.
Both halves of the fix were required:
- Producer: measure the auto-height tile off-flow with
height: autoat a fixed real width, so it sizes to its own content instead of the stretched/constrained row. - Consumer: the preview rejects border-only measurements and waits for a real height before it enters normal flow and positions the badge.
The general principle: a valid intrinsic measurement must contain a non-zero content contribution when the element has content. Border-box minus chrome ≤ ε ⇒ "layout hasn't happened," not "size is 0."
Pre-trust checklist
- Has a layout box (not
display: none). - Measured at the real inline size, including the final scrollbar-gutter state.
- Same CSS context: custom properties, fonts, ancestor classes,
@containerancestry, shadowadoptedStyleSheets. (Moved tobody? You almost certainly broke this.) - Content is real: fonts loaded, images have dimensions /
aspect-ratio, async children arrived — or you're taking the RO settled value. - Right box + deliberate rounding (
Math.ceilfor a container that must not clip). - No transform in the chain contaminating a
getBoundingClientRectread (else useoffsetHeight). - Passed the reject-border-only guard.
- No RO feedback loop (callback doesn't resize the observed box, or bails when unchanged).
Copy-pasteable patterns
React/TS hooks + vanilla equivalents — (A) in-place placeholder + hidden content (the default), (B) off-flow probe, (C) the settle loop and batched N-node measurement, plus animating a container to its content height and the React re-render-clobber gotcha — are in references/measurement-patterns.md. Read it when you need working code rather than the strategy.