react-device-meta-hook

v1.0.4

Published

9 months ago

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

Downloads

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

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

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 class="chrome windows desktop landscape w1440 h900"></html>

You can now write CSS based on these classes:

.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

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:

.ios.safari .footer {
  padding-bottom: 80px;
}

Prevent content cutoff under Android address bar:

.android .page {
  height: 100svh; /* Safe height */
}

Style headers differently in landscape mode:

.landscape .header {
  flex-direction: row;
}

🔗 GitHub Profile

GitHub

🙌 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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme