useScreen

Custom hook that tracks the screen dimensions and properties with debouncing support. Perfect for responsive React applications requiring display information with Next.js integration and TypeScript support.

Loading component...

"use client";import { useScreen } from '@/components/ui/shadcn-io/use-screen';export default function UseScreenDemo() {  const screen = useScreen();  if (!screen) {    return (      <div className="p-4 max-w-sm mx-auto">        <div className="text-center text-muted-foreground">          Screen information not available        </div>      </div>    );  }  const screenData = [    { label: 'Width', value: `${screen.width}px`, color: 'text-blue-600' },    { label: 'Height', value: `${screen.height}px`, color: 'text-green-600' },    { label: 'Available Width', value: `${screen.availWidth}px`, color: 'text-purple-600' },    { label: 'Available Height', value: `${screen.availHeight}px`, color: 'text-orange-600' },    { label: 'Color Depth', value: `${screen.colorDepth} bits`, color: 'text-red-600' },    { label: 'Pixel Depth', value: `${screen.pixelDepth} bits`, color: 'text-indigo-600' },  ];  return (    <div className="space-y-3 p-4 max-w-sm mx-auto">      <div className="space-y-1">        <h3 className="font-semibold">Screen Information</h3>        <p className="text-xs text-muted-foreground">          Your display properties and dimensions        </p>      </div>      <div className="space-y-1">        {screenData.slice(0, 4).map(({ label, value, color }) => (          <div key={label} className="flex justify-between items-center p-1.5 bg-muted rounded text-sm">            <span className="font-medium">{label}</span>            <span className={`font-mono font-bold ${color}`}>              {value}            </span>          </div>        ))}      </div>      <div className="grid grid-cols-2 gap-1 text-xs">        <div className="p-1.5 bg-muted rounded">          <div className="font-medium">Color Depth</div>          <div className="text-red-600 font-mono">{screen.colorDepth} bits</div>        </div>        <div className="p-1.5 bg-muted rounded">          <div className="font-medium">Pixel Depth</div>          <div className="text-indigo-600 font-mono">{screen.pixelDepth} bits</div>        </div>      </div>      <div className="text-xs text-muted-foreground text-center">        Values update automatically on screen changes      </div>    </div>  );}

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

Features

Screen properties tracking providing comprehensive display information including dimensions and color depth
Orientation support with automatic updates for device rotation and screen changes
Debounced updates allowing performance optimization for high-frequency resize events
SSR compatibility with proper server-side rendering support and initialization options
TypeScript overloads providing type-safe usage patterns for different initialization modes
Memory efficient using proper cleanup and event listener management
shadcn/ui integration ideal for responsive layouts and device-specific components

Examples

Advanced Configuration with Debouncing

Loading component...

"use client";import { useState, useEffect } from 'react';import { Button } from "@/components/ui/button";import { Badge } from "@/components/ui/badge";import { Label } from "@/components/ui/label";import { useScreen } from '@/components/ui/shadcn-io/use-screen';export default function UseScreenAdvancedDemo() {  const [debounceDelay, setDebounceDelay] = useState<number | undefined>(undefined);  const [updateCount, setUpdateCount] = useState(0);    const screenImmediate = useScreen();  const screenDebounced = useScreen({     debounceDelay,    initializeWithValue: true   });  const currentScreen = debounceDelay ? screenDebounced : screenImmediate;  useEffect(() => {    setUpdateCount(prev => prev + 1);  }, [currentScreen]);  if (!currentScreen) {    return (      <div className="p-4 max-w-sm mx-auto">        <div className="text-center text-muted-foreground">          Screen information not available        </div>      </div>    );  }  const aspectRatio = (currentScreen.width / currentScreen.height).toFixed(2);  const usableArea = ((currentScreen.availWidth * currentScreen.availHeight) / (currentScreen.width * currentScreen.height) * 100).toFixed(1);    return (    <div className="space-y-3 p-4 max-w-sm mx-auto">      <div className="space-y-2">        <div className="flex items-center justify-between">          <Label className="text-sm font-medium">Screen Monitor</Label>          <Badge variant="secondary" className="text-xs">            {updateCount} updates          </Badge>        </div>                <div className="flex gap-2">          <Button            onClick={() => setDebounceDelay(undefined)}            variant={!debounceDelay ? 'default' : 'outline'}            size="sm"            className="flex-1 h-7 text-xs"          >            Immediate          </Button>          <Button            onClick={() => setDebounceDelay(300)}            variant={debounceDelay === 300 ? 'default' : 'outline'}            size="sm"            className="flex-1 h-7 text-xs"          >            Debounced          </Button>        </div>      </div>      <div className="grid grid-cols-2 gap-1 text-xs">        <div className="p-1.5 bg-muted rounded">          <div className="font-medium">Resolution</div>          <div className="text-blue-600 font-mono">{currentScreen.width}×{currentScreen.height}</div>        </div>        <div className="p-1.5 bg-muted rounded">          <div className="font-medium">Available</div>          <div className="text-green-600 font-mono">{currentScreen.availWidth}×{currentScreen.availHeight}</div>        </div>      </div>      <div className="grid grid-cols-2 gap-1 text-xs">        <div className="p-1.5 bg-muted rounded">          <div className="font-medium">Color Depth</div>          <div className="text-purple-600 font-mono">{currentScreen.colorDepth} bits</div>        </div>        <div className="p-1.5 bg-muted rounded">          <div className="font-medium">Pixel Depth</div>          <div className="text-orange-600 font-mono">{currentScreen.pixelDepth} bits</div>        </div>      </div>      <div className="space-y-1 text-xs">        <div className="flex justify-between p-1.5 bg-muted rounded">          <span>Aspect Ratio:</span>          <span className="font-mono text-indigo-600">{aspectRatio}:1</span>        </div>        <div className="flex justify-between p-1.5 bg-muted rounded">          <span>Usable Area:</span>          <span className="font-mono text-red-600">{usableArea}%</span>        </div>      </div>      <div className="space-y-1">        <div className="flex justify-between text-xs">          <span>Update mode:</span>          <span className="font-mono">{debounceDelay ? `${debounceDelay}ms debounce` : 'immediate'}</span>        </div>        <div className="flex justify-between text-xs">          <span>Total updates:</span>          <span className="font-mono">{updateCount}</span>        </div>      </div>      <div className="text-xs text-muted-foreground text-center">        Change window size to see updates in action      </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 buttonVariants = cva(  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-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",  {    variants: {      variant: {        default:          "bg-primary text-primary-foreground shadow-xs hover:bg-primary/90",        destructive:          "bg-destructive text-white shadow-xs hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",        outline:          "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50",        secondary:          "bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/80",        ghost:          "hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50",        link: "text-primary underline-offset-4 hover:underline",      },      size: {        default: "h-9 px-4 py-2 has-[>svg]:px-3",        sm: "h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5",        lg: "h-10 rounded-md px-6 has-[>svg]:px-4",        icon: "size-9",      },    },    defaultVariants: {      variant: "default",      size: "default",    },  })function Button({  className,  variant,  size,  asChild = false,  ...props}: React.ComponentProps<"button"> &  VariantProps<typeof buttonVariants> & {    asChild?: boolean  }) {  const Comp = asChild ? Slot : "button"  return (    <Comp      data-slot="button"      className={cn(buttonVariants({ variant, size, className }))}      {...props}    />  )}export { Button, buttonVariants }

Demonstrates debounced updates, calculated values, and comprehensive screen property monitoring.

Use Cases

This free open source React component works well for:

Responsive design - Adapt layouts based on screen resolution and available space with Next.js
Device detection - Identify display capabilities for optimal user experience using TypeScript
Orientation handling - Respond to device rotation and screen changes with shadcn/ui components
Performance monitoring - Track screen properties for analytics and optimization using Tailwind CSS
Multi-monitor support - Handle different display configurations and properties

API Reference

useScreen (SSR-safe)

useScreen(options: { initializeWithValue: false }): Screen | undefined

Returns undefined initially, suitable for server-side rendering.

useScreen (Client-side)

useScreen(options?: Partial<UseScreenOptions<true>>): Screen

Returns Screen object immediately, suitable for client-side only usage.

UseScreenOptions

Property	Type	Default	Description
`initializeWithValue`	`boolean`	`true`	Whether to initialize with screen values immediately
`debounceDelay`	`number`	`undefined`	Delay in milliseconds for debounced updates

Screen Properties

Property	Type	Description
`width`	`number`	Total screen width in pixels
`height`	`number`	Total screen height in pixels
`availWidth`	`number`	Available screen width (excluding taskbars)
`availHeight`	`number`	Available screen height (excluding taskbars)
`colorDepth`	`number`	Color depth in bits per pixel
`pixelDepth`	`number`	Pixel depth in bits per pixel
`orientation`	`ScreenOrientation \| null`	Screen orientation object (if supported)

ScreenOrientation Properties

Property	Type	Description
`type`	`string`	Orientation type (portrait-primary, landscape-primary, etc.)
`angle`	`number`	Orientation angle in degrees (0, 90, 180, 270)

Usage Patterns

Basic Screen Information

import { useScreen } from '@repo/use-screen';

function DisplayInfo() {
  const screen = useScreen();
  
  if (!screen) return <div>Loading screen info...</div>;
  
  return (
    <div>
      Screen: {screen.width} × {screen.height}
      Available: {screen.availWidth} × {screen.availHeight}
    </div>
  );
}

SSR-Safe Usage

const screen = useScreen({ initializeWithValue: false });

return (
  <div>
    {screen ? (
      <span>Screen: {screen.width}×{screen.height}</span>
    ) : (
      <span>Screen info loading...</span>
    )}
  </div>
);

Debounced Updates

const screen = useScreen({ 
  debounceDelay: 300,
  initializeWithValue: true 
});

// Screen updates are debounced by 300ms

Responsive Breakpoints

const screen = useScreen();

const getScreenSize = (width: number) => {
  if (width < 768) return 'mobile';
  if (width < 1024) return 'tablet';
  return 'desktop';
};

const screenSize = screen ? getScreenSize(screen.width) : 'unknown';

Implementation Notes

Hook automatically listens to window resize events for screen property updates
Returns undefined during SSR when initializeWithValue is false
Screen object is shallow cloned on updates to ensure proper re-renders
Debouncing is disabled by default for retro-compatibility with immediate updates
Orientation information is only available on browsers that support screen.orientation
Hook uses useEventListener and useIsomorphicLayoutEffect for optimal performance
Proper cleanup is handled automatically when component unmounts
Compatible with all modern browsers that expose the window.screen API

Reactbutton

Reactbadge

Reactlabel

On this page