react-device-meta-hook
Version:
A lightweight React hook that detects the user's browser, operating system, device type (mobile, tablet, desktop), screen orientation, and resolution. It automatically adds meaningful CSS classes to the `<html>` element, enabling responsive design and con
172 lines (121 loc) • 3.9 kB
Markdown
# react-detect-device-info
> 🧠 React hook to detect browser, OS, device type, orientation, resolution, and viewport heights, and apply them as CSS classes to the `<html>` element. Ideal for responsive design and adaptive UI development.
## 📦 Installation
```bash
npm install react-detect-device-info
# or
yarn add react-detect-device-info
```
## 🧩 What It Does
`useDeviceDetect` is a lightweight utility hook for React applications that:
- Detects:
- Browser name and version
- Operating system (Windows, macOS, iOS, Android, etc.)
- Device type (mobile, tablet, desktop)
- Orientation (portrait or landscape)
- Resolution (width × height)
- Viewport height metrics: `dvh`, `lvh`, `svh`
- Adds corresponding CSS classes to the `<html>` element.
- Provides all the information via callback for JavaScript-level usage.
## 🎯 Why Use This?
Responsive design often depends on breakpoints, media queries, or JS-based logic. This hook enables:
- ✅ **Device-specific theming**
- ✅ **OS or browser-specific styling**
- ✅ **Fine-grained control over orientation/layout**
- ✅ **Dynamic viewport unit support (for mobile browser UI adjustments)**
- ✅ **Cleaner CSS without extra wrapper classes**
## 🚀 Quick Start
### 1. Use the Hook in Your App
```tsx
import React from "react";
import { useDeviceDetect } from "react-detect-device-info";
function App() {
useDeviceDetect((info) => {
console.log("Device Info:", info);
});
return <div>Hello world</div>;
}
export default App;
```
### 2. Resulting `<html>` Classes Example
```html
<html class="chrome windows desktop landscape w1440 h900"></html>
```
> You can now write CSS based on these classes:
```css
.desktop .header {
padding: 20px;
}
.ios .button {
font-size: 16px;
}
.w375.h812 {
font-size: 14px;
}
```
## 📋 API
### `useDeviceDetect(callback?)`
| Parameter | Type | Description |
| ---------- | ---------------------------- | ---------------------------------------------------- |
| `callback` | `(info: DeviceInfo) => void` | Optional. Receives detailed info object as argument. |
### `DeviceInfo` Object Shape
```ts
interface DeviceInfo {
browser: {
name: string;
version: string;
};
os: string;
deviceType: "mobile" | "tablet" | "desktop";
orientation: "portrait" | "landscape";
resolution: {
width: number;
height: number;
};
viewportHeights: {
dvh: number; // dynamic viewport height
lvh: number; // largest possible viewport height
svh: number; // smallest viewport height (when address bar shown)
};
}
```
## 🧠 How It Helps in Development
- **Adaptive CSS Styling**: Apply styles conditionally without writing JS logic in every component.
- **Device-Aware Layouts**: Easily build experiences optimized for phones, tablets, or desktops.
- **Safe Viewport Handling**: Use `dvh`, `lvh`, and `svh` to deal with mobile browser toolbars (keyboard, address bar).
- **Debug-Friendly**: With `<html>` classes like `.android`, `.firefox`, `.tablet`, you can test layouts more easily.
- **Avoid Overengineering**: Let HTML and CSS handle device-based decisions without bloated layout logic.
## 🧪 Example Use Cases
- Apply extra spacing on iOS Safari where needed:
```css
.ios.safari .footer {
padding-bottom: 80px;
}
```
- Prevent content cutoff under Android address bar:
```css
.android .page {
height: 100svh; /* Safe height */
}
```
- Style headers differently in landscape mode:
```css
.landscape .header {
flex-direction: row;
}
```
## 🔗 GitHub Profile
- [GitHub](https://github.com/aditya-jha55)
## 🙌 Acknowledgements
This hook was inspired by the need for responsive CSS control without bloated JS logic. Special thanks to the growing community focused on adaptive UX/UI.