ResizeObserver Polyfill

resize-observer-polyfill is a lightweight implementation of the ResizeObserver API for browsers that predate native support. It’s built on MutationObserver, falling back to Mutation Events only where necessary, so it avoids polling and only recalculates layout in response to actual DOM changes; it also correctly picks up size changes from CSS transitions, animations, and dynamic pseudo-classes like :hover.

Designed to be used as a ponyfill (imported directly rather than patching the global window object), it became one of the standard dependencies for UI libraries and component frameworks that needed reliable element-resize detection before ResizeObserver reached universal browser support, and remains heavily downloaded as a safety-net dependency in libraries supporting older environments.

What You Get

• A drop-in ResizeObserver class matching the native API’s observe()/unobserve()/disconnect() methods
• MutationObserver-based change detection with a Mutation Events fallback for older browsers
• No polling — layout recalculation only happens in response to actual DOM/style changes
• Detection of size changes from CSS transitions, animations, and dynamic pseudo-classes like :hover
• TypeScript and Flow type definitions bundled in the package

Common Use Cases

• Adding reliable element-resize detection to component libraries that must support older browsers
• Powering responsive, container-query-style layouts before native ResizeObserver/CSS container queries were available
• Triggering re-renders in charting or canvas libraries when their container element changes size
• Detecting size changes caused by dynamic content, CSS animations, or hover-triggered layout shifts

Under The Hood

Architecture ResizeObserver.js exposes the public class that delegates all real work to a shared ResizeObserverController singleton, which maintains the list of active observations (ResizeObservation.js) and schedules a batched callback dispatch; the actual change-detection mechanism is abstracted behind an SPI (ResizeObserverSPI.js) so the MutationObserver-based strategy (with a Mutation Events fallback under src/shims) can be swapped without touching the public API. Tech Stack Plain JavaScript (no runtime dependencies), built with Rollup into both CommonJS (dist/ResizeObserver.js) and ES module (dist/ResizeObserver.es.js) bundles, with hand-written .d.ts and Flow type definitions shipped alongside; testing uses Karma against real browsers (including Sauce Labs cross-browser runs) plus a Node-based spec runner. Code Quality The tests/ directory includes both browser-run Karma specs and a dedicated Node test entry point (tests/node/index.js), with ESLint enforced via npm run test:lint before any spec run — a solid but browser-API-focused test setup appropriate for a small polyfill; the project has seen no material commits since its 2018 1.5.1 release, reflecting that native ResizeObserver support has since made it feature-complete rather than abandoned. API Design The library deliberately mirrors the native ResizeObserver constructor/callback signature exactly, so adopting it requires zero API-learning curve beyond importing it as a named ponyfill rather than relying on a global — the tradeoff being that, being frozen since 2018, it won’t track any spec changes made to the native API after that point.