React useScreen Hook

Ever tried to detect screen properties in React and ended up with window.screen access confusion, missing orientation change events, or broken multi-monitor support? You know the drill—manually checking window.screen properties, forgetting to listen for orientation changes, dealing with SSR hydration mismatches, missing debouncing for performance. This free open source React useScreen custom hook handles all that screen detection complexity so you can focus on building responsive features instead of debugging display property edge cases in your React applications.

useScreen showcase

Real-time screen property tracking with orientation and dimension monitoring:

"use client";import { Badge } from "@/components/ui/badge";import { Label } from "@/components/ui/label";import { useScreen } from '@/components/ui/shadcn-io/use-screen';export default function UseScreenDemo() {  const screen = useScreen();  if (!screen) {    return (      <div className="p-6 max-w-sm mx-auto space-y-4">        <div className="text-center space-y-1">          <h3 className="text-lg font-semibold">Screen Information</h3>          <p className="text-sm text-muted-foreground">Display properties and dimensions</p>        </div>        <div className="bg-muted rounded p-2 min-h-[40px] flex items-center justify-center">          <span className="text-sm text-muted-foreground">Loading screen data...</span>        </div>      </div>    );  }  const aspectRatio = (screen.width / screen.height).toFixed(2);  return (    <div className="p-6 max-w-sm mx-auto space-y-4">      {/* Header */}      <div className="text-center space-y-1">        <h3 className="text-lg font-semibold">Screen Information</h3>        <p className="text-sm text-muted-foreground">Display properties and dimensions</p>      </div>            {/* Resolution Display */}      <div className="space-y-2">        <Label className="text-sm font-medium">Resolution</Label>        <div className="bg-muted rounded p-2 min-h-[40px] flex items-center justify-center">          <Badge variant="default" className="text-sm px-3 py-1 font-mono">            {screen.width} × {screen.height}px          </Badge>        </div>      </div>      {/* Properties Grid */}      <div className="grid grid-cols-2 gap-2 h-16">        <div className="bg-muted rounded p-2 flex flex-col justify-center items-center">          <Label className="text-xs text-muted-foreground">Available</Label>          <span className="text-sm font-mono">{screen.availWidth}×{screen.availHeight}</span>        </div>        <div className="bg-muted rounded p-2 flex flex-col justify-center items-center">          <Label className="text-xs text-muted-foreground">Aspect Ratio</Label>          <span className="text-sm font-mono">{aspectRatio}:1</span>        </div>      </div>      {/* Depth Information */}      <div className="grid grid-cols-2 gap-2 h-16">        <div className="bg-muted rounded p-2 flex flex-col justify-center items-center">          <Label className="text-xs text-muted-foreground">Color Depth</Label>          <span className="text-sm font-mono">{screen.colorDepth} bits</span>        </div>        <div className="bg-muted rounded p-2 flex flex-col justify-center items-center">          <Label className="text-xs text-muted-foreground">Pixel Depth</Label>          <span className="text-sm font-mono">{screen.pixelDepth} bits</span>        </div>      </div>      {/* Instructions */}      <div className="text-center min-h-[16px] flex items-center justify-center">        <div className="text-xs text-muted-foreground">          Updates automatically on screen changes        </div>      </div>    </div>  );}

import * as React from "react"import { Slot } from "@radix-ui/react-slot"import { cva, type VariantProps } from "class-variance-authority"import { cn } from "@/lib/utils"const badgeVariants = cva(  "inline-flex items-center justify-center rounded-md border px-2 py-0.5 text-xs font-medium w-fit whitespace-nowrap shrink-0 [&>svg]:size-3 gap-1 [&>svg]:pointer-events-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive transition-[color,box-shadow] overflow-hidden",  {    variants: {      variant: {        default:          "border-transparent bg-primary text-primary-foreground [a&]:hover:bg-primary/90",        secondary:          "border-transparent bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90",        destructive:          "border-transparent bg-destructive text-white [a&]:hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",        outline:          "text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground",      },    },    defaultVariants: {      variant: "default",    },  })function Badge({  className,  variant,  asChild = false,  ...props}: React.ComponentProps<"span"> &  VariantProps<typeof badgeVariants> & { asChild?: boolean }) {  const Comp = asChild ? Slot : "span"  return (    <Comp      data-slot="badge"      className={cn(badgeVariants({ variant }), className)}      {...props}    />  )}export { Badge, badgeVariants }

This free open source React hook simplifies screen information access with TypeScript support for modern JavaScript applications. Whether you're building device-adaptive layouts, orientation-aware interfaces, or display-specific features in your Next.js projects, this React hook keeps your screen data accurate and reactive.

Installation

npx shadcn@latest add https://www.shadcn.io/registry/use-screen.json

npx shadcn@latest add https://www.shadcn.io/registry/use-screen.json

pnpm dlx shadcn@latest add https://www.shadcn.io/registry/use-screen.json

bunx shadcn@latest add https://www.shadcn.io/registry/use-screen.json

Why most screen detection implementations suck

Look, you could keep accessing window.screen directly and manually listening for orientation changes. But then you hit the screen detection complexity—missed orientation events, performance issues from unthrottled updates, SSR incompatibility, inconsistent multi-monitor behavior in React applications.

Most developers access window.screen properties directly without proper event handling, missing crucial orientation changes when users rotate devices in TypeScript components. Or they poll screen properties without debouncing, causing performance issues from constant re-renders. Some forget about SSR considerations entirely and get hydration mismatches when screen properties differ between server and client in Next.js projects.

This React hook uses optimized event listening under the hood, with automatic orientation change detection and proper SSR handling in JavaScript applications. The browser handles all the screen events, plus you get debounced updates and comprehensive property tracking in one call.

Plus it handles all the edge cases—SSR compatibility with controlled hydration, orientation API fallbacks, automatic cleanup and memory management in React development. No more scattered screen property checks or broken device rotation handling.

This free open source React hook manages screen state while you focus on building features. Whether you're creating React applications, Next.js interfaces, or TypeScript components, reliable screen detection keeps your JavaScript development adaptive.

Features

• Screen properties tracking providing comprehensive display information including dimensions and color depth in React applications
• Orientation support with automatic updates for device rotation and screen changes in TypeScript components
• Debounced updates allowing performance optimization for high-frequency resize events in Next.js projects
• SSR compatibility with proper server-side rendering support and initialization options in JavaScript development
• TypeScript overloads providing type-safe usage patterns for different initialization modes for React frameworks
• Memory efficient using proper cleanup and event listener management in modern applications
• Free open source designed for modern React development workflows

When you'll actually use this

Real talk—this isn't for basic responsive design in React applications. CSS media queries and viewport units handle most screen-based styling perfectly. But when you need actual screen hardware information for device detection or multi-monitor support, this React hook delivers in Next.js projects.

Perfect for:

• Device capability detection - Check screen resolution and color depth for optimal graphics built with TypeScript
• Multi-monitor applications - Detect multiple displays and available screen real estate using React patterns
• Orientation-aware interfaces - Respond to device rotation with layout changes in JavaScript applications
• High-DPI optimization - Adapt content quality based on pixel density in React components
• Analytics and monitoring - Track user display capabilities for optimization insights in Next.js applications
• Kiosk or fullscreen apps - Utilize full screen dimensions for immersive experiences using TypeScript safety

API Reference

useScreen

useScreen<T extends boolean = true>(
  options?: UseScreenOptions<T>
): T extends false ? Screen | undefined : Screen

UseScreenOptions

Screen Properties

ScreenOrientation Properties

Common gotchas

Screen vs viewport are different concepts: This React hook tracks physical screen hardware properties, not browser viewport in React applications. For responsive web design, use viewport-based approaches instead of screen dimensions.

Orientation API has limited support: The screen.orientation object might be null on some browsers in TypeScript components. Always check for existence before accessing orientation properties.

Multi-monitor support is basic: The React hook reports the primary display's properties in Next.js projects. True multi-monitor detection requires additional browser APIs beyond the standard screen object.

SSR requires special handling: Use initializeWithValue: false to prevent hydration mismatches in JavaScript applications. The hook will return undefined initially and update with real data after client hydration.

Debouncing affects responsiveness: While debouncing improves performance, it can delay orientation change updates in React frameworks. Balance performance needs with responsiveness requirements.

Browser compatibility varies: Not all screen properties are available in every browser in TypeScript projects. Always provide fallbacks for missing properties or APIs.

Related hooks you will also like

Questions you might have