Prerequisites
- Familiarity with the CSS box model and box-sizing.
- Basic knowledge of ResizeObserver and getBoundingClientRect.
Implementation decision
Choose a property by the diagnostic question you’re asserting. If you care about the inner usable area, read contentBoxSize. If you care about the element’s outer layout footprint (what contributes to surrounding layout), read borderBoxSize. If you need physical pixel counts (for canvas placement or crisp rendering), use devicePixelContentBoxSize when the browser provides it. If the element is visually transformed (scale != 1), ResizeObserver fields are the wrong tool — measure painted geometry with getBoundingClientRect.
Expected result
- Assertions that explicitly name the edge they check become stable and meaningful. A content-box assertion won’t be surprised by box-sizing: border-box, and a border-box assertion won’t be surprised by added padding.
- Tests that need device-pixel precision will avoid subtle off-by-one physical pixel issues when they opt into devicePixelContentBoxSize.
One limitation
ResizeObserver reports layout boxes and does not capture post-transform painted size. When transforms are part of the behavior you must verify, the decision must be to use a visual geometry read (getBoundingClientRect), not another ResizeObserverEntry field.
Working example
export function computeBoxSizes({width, padding = 0, border = 0, devicePixelRatio = 1} = {}) {
// All inputs are CSS pixels. We return the three ResizeObserverEntry-style sizes
// as simple objects: {inlineSize, blockSize} in CSS pixels for content/border
// and in device pixels for devicePixelContentBoxSize.
const contentInline = Math.max(0, width - padding * 2 - border * 2);
const borderInline = Math.max(0, width);
const contentBoxSize = {inlineSize: contentInline, blockSize: 0};
const borderBoxSize = {inlineSize: borderInline, blockSize: 0};
const devicePixelContentBoxSize = {
inlineSize: Math.round(contentInline * devicePixelRatio),
blockSize: 0,
};
return {contentBoxSize, borderBoxSize, devicePixelContentBoxSize};
}
export function pickResizeObserverProperty({
wants = "layout", // "layout" means the untransformed CSS layout edge
boxSizing = "content-box", // "content-box" or "border-box"
transformScale = 1, // CSS transform scale applied to element (visual only)
devicePixelRatio = 1,
measured = {}, // optional precomputed sizes from computeBoxSizes()
} = {}) {
// This function implements a deterministic, testable policy mapping a
// requested measurement (layout vs visual vs device pixels) and the
// element's box-sizing/transform/DPR to the ResizeObserver-derived
// property a test should read — or a note that ResizeObserver doesn't
// provide that value (call getBoundingClientRect instead).
// We do not run inside a browser here; instead this is a pure algorithmic
// decision helper. Real browser measurements may differ slightly.
// Normalize inputs
const wantsNormalized = wants;
const boxNorm = boxSizing === "border-box" ? "border-box" : "content-box";
const scale = Number(transformScale) || 1;
const dpr = Number(devicePixelRatio) || 1;
// If caller asked for device pixels of the content box, recommend
// devicePixelContentBoxSize when available (modern browsers).
if (wants === "device-pixels-content") {
return {property: "devicePixelContentBoxSize", reason: "content box in device pixels"};
}
// If they want the layout edge (untransformed): choose content vs border.
if (wantsNormalized === "layout") {
if (boxNorm === "border-box") {
return {property: "borderBoxSize", reason: "box-sizing: border-box — borderBoxSize matches layout edge"};
}
return {property: "contentBoxSize", reason: "box-sizing: content-box — contentBoxSize matches layout edge"};
}
// If they want the visual edge after transforms, ResizeObserver entry
// properties report layout boxes (pre-transform). A transform scale
// applied only affects painting; to measure visual size use
// getBoundingClientRect (not a ResizeObserverEntry property).
if (wantsNormalized === "visual") {
if (scale !== 1) {
return {property: null, reason: "element is transformed; use element.getBoundingClientRect() — ResizeObserver box sizes are layout boxes and ignore transforms"};
}
// No transform: visual == layout, so fall back to layout logic.
return pickResizeObserverProperty({wants: "layout", boxSizing: boxNorm, devicePixelRatio: dpr});
}
// Fallback
return {property: null, reason: "unknown request"};
}
Read the full article: https://chriseugenerodriguez.com/blog/resizeobserver-entry-property-diagnostics