use-device-pixel-ratio

use-device-pixel-ratio is a lightweight React hook for reading a browser’s device pixel ratio (DPR) — the ratio between physical and CSS pixels used to serve crisp images and render high-density graphics. Unlike a one-time window.devicePixelRatio read, the hook is reactive: it subscribes to a matchMedia query and updates automatically if the browser window moves to a display with a different DPR.

By default the value is rounded down and capped at 3, so most apps only ever see 1, 2, or 3 — options exist to change the cap, disable rounding, or set a fallback for server rendering and unsupported browsers. A plain getDevicePixelRatio function is also exported for use outside of React components.

What You Get

• A React hook (useDevicePixelRatio) that re-renders your component when the display’s DPR changes
• A standalone getDevicePixelRatio function for reading the DPR outside React’s render cycle
• Sensible defaults (rounds down, caps at 3, defaults to 1) that cover the common responsive-image use case out of the box
• TypeScript types and a small Vite-powered demo app shipped in the repo

Common Use Cases

• Serving the right pixel density for responsive images from a CDN
• Scaling canvas/WebGL drawing buffers for crisp rendering on high-DPI screens
• Providing a safe default DPR value during server-side rendering
• Reacting to DPR changes when a browser window moves across displays with different pixel densities

Under The Hood

Architecture The entire package is a single index.ts file exporting both useDevicePixelRatio and a pure getDevicePixelRatio function; the hook wraps the pure function in useState/useEffect, subscribing to a matchMedia query keyed to the current DPR threshold and re-subscribing whenever the DPR or options change, with a Safari-compatible addListener/removeListener fallback for browsers that lack addEventListener on MediaQueryList. There are no internal modules, layers, or extra state beyond React’s built-in hooks, so the whole behavior is traceable in one short file.

Tech Stack Written in TypeScript (strict mode, ESNext target), built with microbundle to emit CommonJS, ESM, and UMD bundles plus type declarations, developed alongside a small Vite-powered demo app, tested with Jest + ts-jest under a jsdom environment, and linted with ESLint (eslint-config-sanity) and Prettier. The only runtime dependency is a peer dependency on React >=16.8.0 for hook support.

Code Quality index.test.tsx exercises both the hook and the underlying getDevicePixelRatio function across rounding, capping, default-value, and reactive matchMedia-change scenarios, including a hand-rolled matchMedia mock to simulate DPR changes; CI runs the suite across Node 14, 16, and 18. The module has no explicit error handling since it performs no fallible operations, naming is consistent and descriptive throughout the single source file, and the public API is documented with TSDoc comments.

API Design A two-tier API — a hook plus a plain function counterpart — lets consumers use the DPR logic inside or outside a React render. Defaults (round: true, maxDpr: 3, defaultDpr: 1) mean zero-config usage covers the common case, and all options are a single optional object rather than positional arguments, keeping the surface minimal and self-documenting.