# react-device-detector

> Device-class rendering for React 17, 18 and 19, with zero runtime dependencies. Five view components plus a `useDevice()` hook branch on device class; the detector itself is a pure function exported separately at `react-device-detector/server`, so server code can compute the device from a request user-agent and get a correct first paint. SSR-safe: views render `null` until detection completes rather than flashing wrong-device content.

The honest boundary: user-agent detection is a heuristic, not a fact, and a component cannot know the device during server rendering — there is no device to inspect, only an HTTP request.

## Install

```sh
npm install react-device-detector
```

Peer dependency: `react` (^17 || ^18 || ^19). Ships ESM and CommonJS with TypeScript declarations, and is marked `sideEffects: false`. For the current published version see the npm page below.

## API

- [`MobileView` `DesktopView` `IOSView` `AndroidView` `TabletView`](https://github.com/moji2002/react-device-detector#usage): Components that render children only on the matching device class. All accept `renderWhileDetecting`.
- [`useDevice()`](https://github.com/moji2002/react-device-detector#usage): Hook returning `{ isMobile, isDesktop, isIOS, isAndroid, isTablet, isDetecting }`.
- [`detectDevice({ userAgent, maxTouchPoints })`](https://github.com/moji2002/react-device-detector#nextjs-app-router): Pure function, usable on the server. Exported from both `react-device-detector` and `react-device-detector/server`.
- [`setServerDevice(info)`](https://github.com/moji2002/react-device-detector#the-detection-gap-stated-plainly): Seeds the detected value so the first paint is correct.
- `DeviceProvider`: Context provider taking a `DeviceInfo` — a plain object of booleans, so it serializes cleanly across the Server/Client Component boundary.

## Entry points

- `react-device-detector` — the main entry. Ships the `"use client"` directive because it uses hooks. You can still import the views directly into a Server Component and they work.
- `react-device-detector/server` — the pure detector, with **no** `"use client"`. This is the one to call from server code.

## Notes for code generation

- **Views render `null` until detection completes.** That is deliberate — it is what removed v1's flash of wrong-device content. If something must be on screen during that window, pass `renderWhileDetecting`.
- **Do not call `detectDevice` from the main entry in server code** when the framework is strict about client modules; import from `react-device-detector/server`, which carries no `"use client"`.
- **Header-based detection cannot see `maxTouchPoints`**, so an iPadOS 13+ device looks like a Mac to the server. The client corrects it right after hydration. When iPad accuracy on the first paint matters, use `<DesktopView renderWhileDetecting={false}>` and let the client decide.
- **Prefer a CSS media query when one can answer the question.** `pointer: coarse` and `min-width` describe the actual viewport; a user-agent string is a guess. Reach for this library when you must branch in JavaScript on device *class* and accept a heuristic's error rate.
- Do not describe this as reliable device identification. UA detection is defeated by spoofing, by browsers that freeze or reduce their UA string, and by devices that do not exist yet.
- Use `isDetecting` to render a skeleton rather than guessing a default.
- There is no `react-dom` peer beyond React itself; v2's only peer is `react`.

## Server-side detection

```tsx
// app/layout.tsx — Next.js App Router
import { headers } from "next/headers";
import { detectDevice } from "react-device-detector/server";
import { DeviceProvider } from "react-device-detector";

const ua = (await headers()).get("user-agent") ?? "";
const device = detectDevice({ userAgent: ua, maxTouchPoints: 0 });

// <DeviceProvider value={device}>{children}</DeviceProvider>
```

## Docs

- [README — full documentation](https://github.com/moji2002/react-device-detector#readme): usage, Next.js App Router, the v1 migration, the detection gap, accuracy, and the API table.
- [npm package](https://www.npmjs.com/package/react-device-detector): current published version.
- [Project notes](https://worksonmy.dev/projects/react-device-detector): design rationale.

## Optional

- [Upgrading from v1](https://github.com/moji2002/react-device-detector#-upgrading-from-v1): v1 had two bugs serious enough to force a breaking change — every SSR page had a hydration mismatch, and modern iPads were detected as desktops.
- [Issues](https://github.com/moji2002/react-device-detector/issues)