ResizeObserver fills a genuine gap the traditional window resize event leaves entirely uncovered: detecting when a specific element's own dimensions change, regardless of whether the browser window itself moved at all.
1The Real Gap In window's resize Event
window.addEventListener('resize', callback) is strictly tied to changes in the actual browser viewport dimensions — resizing the browser window, rotating a mobile device, or the OS changing zoom level. It has no awareness whatsoever of an individual element's size changing for any other reason.
A common real-world scenario this misses entirely: a sidebar toggles open, causing the main content area to shrink significantly — the browser window itself never changed size, so resize never fires, even though a specific element's actual rendered dimensions changed substantially and a responsive component within it might genuinely need to react.
2ResizeObserver: Tracking A Specific Element Directly
new ResizeObserver(callback), with .observe(element) registering a specific element for tracking, efficiently notifies the callback whenever that element's actual content box dimensions change — for any reason at all: a parent flex or grid layout reflowing, a sibling element's content changing height, a sidebar toggle, a CSS class change, or genuine window resizing too.
This directness is exactly what fills the gap from the previous section: since it observes the element's own actual rendered size rather than inferring it indirectly from window dimensions, it correctly fires for every real cause of that specific element's size changing, not just viewport-driven ones.
3Container-Relative, Component-Level Responsiveness
A genuine, recurring layout problem: a reusable card component might render in a wide main content area on one page and a narrow sidebar on another, at the exact same overall viewport width — traditional viewport-based CSS media queries have no way to distinguish these two cases, since they only know the browser window's size, not any individual component's actual rendered width.
Before native CSS container queries existed to solve this declaratively, ResizeObserver was the standard JavaScript-based technique for building components that adapt their own internal layout based on their actual container's size — observing the component's own element and applying different classes or styles based on its measured width, achieving genuine container-relative responsive design.
4Step-by-Step Breakdown
Detecting An Element's Own Size Changes, Not Just The Window's. The window resize event only fires when the browser window itself changes size — useless for detecting when a specific component's container shrinks due to a sidebar opening, a parent flex/grid layout change, or dynamic content elsewhere on the page. Resize Observer fills exactly this gap.
window resize Only Tracks The Whole Window. The traditional window.addEventListener('resize', ...) only fires when the actual browser viewport dimensions change — it never fires when a specific element's size changes for other reasons, like a CSS Grid layout reflowing or a sidebar toggling open.
The window resize Event's Limitation. Does the window resize event fire when a sidebar toggles open, causing a specific content element to shrink, but the browser window itself stays the same size?
- →Yes, it fires whenever any element's size changes for any reason
- →No, it only fires when the actual browser window/viewport dimensions change
- →It fires inconsistently depending on the browser
ResizeObserver Tracks Any Specific Element's Size. new ResizeObserver(callback), with .observe(element), efficiently notifies the callback whenever that specific element's content box dimensions change, for any reason — parent layout changes, dynamic content, sidebar toggles, CSS changes — not just whole-window resizing.
ResizeObserver's Broader Coverage. Would ResizeObserver detect a specific element shrinking due to a sidebar opening elsewhere on the page, even with the browser window itself unchanged?
- →No, it has the exact same window-only limitation as the resize event
- →Yes, it detects the observed element's size change regardless of what caused it
- →Only if the size change was caused specifically by a CSS media query
Powers Container Queries And Responsive Components. Before native CSS container queries existed, ResizeObserver was the JavaScript-based way to build components that adapt their own layout based on their container's size rather than the viewport's — a reusable card component that looks different when narrow versus wide, regardless of overall page width.
ResizeObserver And Container-Relative Design. What layout problem does ResizeObserver help solve that traditional viewport-based CSS media queries can't address?
- →It solves the exact same problem as media queries, just redundantly
- →Adapting a component's layout based on its own container's size, not the overall viewport size
- →Detecting the user's preferred color scheme
Resize Observer Introduced. You now understand the real gap window's resize event leaves for element-level size changes, how ResizeObserver fills it by tracking any specific element's dimensions directly, and its historical role powering container-relative, component-level responsive design — completing the Browser APIs module.
Mark An Element For Resize Watching. ResizeObserver needs a hook to know which element's size changes to react to.
Level Up 🚀
Advanced cheat sheets, SEO tricks, and interview prep for this topic.
Browser Support
Fully supported.
Fully supported.
Fully supported.
Fully supported.
Accessibility (A11y)
1Components That Adapt Layout Based On Container Size Should Preserve Reading Order And Focus Order
As with any dynamic layout change, ResizeObserver-driven component adaptations must ensure the DOM order (which drives screen reader and keyboard navigation order, per the Mobile-First HTML lesson) remains logical regardless of the applied visual layout.
SEO Implications
- 1
Genuinely Reusable, Container-Aware Components Reduce Duplicate Component Variants And Associated Code Weight
A single component that adapts to its container, rather than requiring separate hardcoded 'sidebar version' and 'main content version' implementations, indirectly supports leaner codebases and smaller JavaScript bundles.
Best Practices
Use ResizeObserver Specifically When A Component Needs To Respond To Its Own Container's Size, Not The Viewport's
For genuine viewport-level responsiveness, CSS media queries remain simpler and more appropriate; reserve ResizeObserver for the specific container-relative case media queries can't address.
Prefer Native CSS Container Queries Where Sufficient, Falling Back To ResizeObserver For More Complex Cases
Container queries now handle many of the same use cases declaratively without JavaScript; ResizeObserver remains valuable for cases requiring more complex logic than CSS alone can express.
Frequent Bugs
A responsive component doesn't adapt correctly when it renders inside a narrow sidebar versus a wide main content area, despite correct media-query-based CSS.
This is exactly the case media queries can't address — implement ResizeObserver (or CSS container queries) to respond to the component's own actual rendered width instead of viewport width.
A dashboard widget's internal chart doesn't resize when a sidebar toggle changes its available width.
The window resize event never fires for this case since the viewport itself is unchanged; use ResizeObserver on the widget's own container element instead.
Real-World Examples
A Container-Aware Card Component
A reusable card component applying a compact layout class when its own container is narrow, regardless of overall viewport width.
const cardObserver = new ResizeObserver((entries) => {
entries.forEach(entry => {
entry.target.classList.toggle('compact', entry.contentRect.width < 300);
});
});
document.querySelectorAll('.card').forEach(card => cardObserver.observe(card));