feat: add useDevicePixelRatio

[umsungjun]

Added

useDevicePixelRatio(), a hook returning window.devicePixelRatio for @2x/@3x asset selection, canvas backing store scaling, and tile resolution requests.

import { useDevicePixelRatio } from 'react-device-check';

const dpr = useDevicePixelRatio();

Reactive: the value moves on browser zoom, on a display scale change, and when the window crosses screens of different densities. Server render and hydration first paint both report 1, so server and client HTML always match, and the real ratio arrives one render later.

The ratio has its own store instead of a field on DeviceInfo, so useDevice() keeps exactly two listeners and its budget stays flat.

import	before	after
everything	1.5 kB	1.63 kB
{ useIsMobile }	1.09 kB	1.09 kB
{ useDevice }	1.33 kB	1.33 kB
{ detectDevice }	830 B	830 B
{ useDevicePixelRatio }	n/a	609 B

13 new unit tests (85 → 98). E2E asserts the ratio across all six device profiles, reading the expected value from the Playwright descriptor's deviceScaleFactor so the matrix covers 1, 2, 2.5 and 3.

Docs

• API reference section in both READMEs, plus a row in the website API table. Deliberately not in the hero copy or the feature cards, since reading a ratio involves no detection.
• Three known limitations: the server cannot know the ratio and no header carries it, browser zoom is indistinguishable from a genuinely denser screen, and Safari before 16 has no resolution media query support so the value never updates there.
• The ~1.5 kB claim moves to ~1.6 kB everywhere it appears, and the unit test count to 98.
• Korean copy pass over README.ko.md and website/content/ko.ts: causal links now run through sentence structure rather than connective adverbs, and one sentence-wide bold came out. One claim was corrected on the way: a correction render keeps CLS at zero because it does not touch geometry, not merely because it lands after the fact.
• CLAUDE.md gains the new modules and the invariant that the ratio stays out of DeviceInfo. Its count-sync instruction now names the website files it was missing.

Also

• listen/unlisten (the Safari < 14 addListener fallback) moved from core/store.ts to core/media.ts, since both stores need them.
• *.tsbuildinfo added to .gitignore.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
react-device-check	Ready	Preview	Aug 18, 2026 7:19am

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 95.55556% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/core/media.ts	66.66%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Adds a new useDevicePixelRatio() hook to the library, backed by a dedicated reactive DPR store, so consumers can reactively read window.devicePixelRatio while preserving the existing SSR and bundle-size contracts.

Changes:

• Introduces src/core/dpr.ts plus useDevicePixelRatio() hook/export, with SSR default of 1 and lazy matchMedia('(resolution: Xdppx)') subscription.
• Extracts shared matchMedia listener helpers into src/core/media.ts and updates existing stores to reuse them.
• Updates unit/E2E tests and documentation/website copy to cover the new hook and updated size/test-count claims.

Reviewed changes

Copilot reviewed 20 out of 21 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
website/tsconfig.tsbuildinfo	Adds a TypeScript build info artifact (should not be tracked).
website/lib/seo.ts	Updates site description size claim and adds DPR-related keyword.
website/content/en.ts	Updates hero badge/test-count copy and adds API row for useDevicePixelRatio().
website/content/ko.ts	Updates hero badge/test-count copy and adds API row for useDevicePixelRatio().
src/core/media.ts	New shared listen/unlisten helpers for matchMedia change events.
src/core/dpr.ts	New DPR reactive store with SSR default 1 and resolution-query listener.
src/useDevicePixelRatio.ts	New public hook using useSyncExternalStore (or fallback) wired to the DPR store.
src/index.ts	Exports useDevicePixelRatio from the public entrypoint.
src/core/store.ts	Switches to shared listen/unlisten helpers (removes local copies).
src/test/dpr.test.ts	New unit tests covering DPR store behavior and listener lifecycle.
src/test/helpers.ts	Adds stubDevicePixelRatio and dprQuery helpers for DPR tests.
src/test/hooks.test.tsx	Adds hook-level tests for useDevicePixelRatio() behavior and non-interference with useDevice().
src/test/setup.ts	Resets DPR store between tests to avoid state leakage.
src/test/ssr.test.tsx	Adds SSR safety regression test for useDevicePixelRatio() returning 1 on server.
e2e/device-detection.spec.ts	Extends Playwright matrix to assert DPR in CSR/SSR flows using deviceScaleFactor.
examples/basic/App.tsx	Displays DPR in the CSR example and updates user hint text.
examples/nextjs/app/DeviceDemo.tsx	Displays live DPR and captures first-paint DPR (1) in the SSR example.
README.md	Documents useDevicePixelRatio(), updates bundle-size/test-count claims, and adds limitations.
README.ko.md	Korean docs updates mirroring README changes and adds DPR limitations.
package.json	Adds size-limit budget entry for { useDevicePixelRatio } and adds related keywords.
CLAUDE.md	Updates architecture/testing guidance and invariants to include the DPR store and hook.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.