useWindowSize

Window dimension tracking with debouncing and SSR support. Perfect for React applications requiring responsive design with Next.js integration and TypeScript support.

Loading component...

Installation

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

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

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

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

Features

Real-time dimension tracking with automatic window resize event handling
Debouncing support with configurable delay to optimize performance during rapid resize events
SSR compatibility designed for Next.js server-side rendering with proper hydration handling
TypeScript overloads with complete type safety for both SSR and CSR usage patterns
Memory efficient with optimized event listeners and automatic cleanup on unmount
Flexible initialization supporting both immediate values and undefined states for server environments

Examples

Advanced Responsive Dashboard

Loading component...

"use client";import * as React from "react";import { Badge } from "@/components/ui/badge";import { Button } from "@/components/ui/button";import { Input } from "@/components/ui/input";import { Label } from "@/components/ui/label";import { useWindowSize } from "@/components/ui/shadcn-io/use-window-size";export default function UseWindowSizeAdvancedDemo() {  const { width = 0, height = 0 } = useWindowSize();  const debouncedSize = useWindowSize({ debounceDelay: 500 });    // Custom debounce delay state  const [customDelay, setCustomDelay] = React.useState(200);  const customDebouncedSize = useWindowSize({ debounceDelay: customDelay });  // Responsive breakpoints  const getBreakpoint = (width: number) => {    if (width < 640) return { name: 'xs', color: 'destructive' as const };    if (width < 768) return { name: 'sm', color: 'default' as const };    if (width < 1024) return { name: 'md', color: 'secondary' as const };    if (width < 1280) return { name: 'lg', color: 'outline' as const };    if (width < 1536) return { name: 'xl', color: 'default' as const };    return { name: '2xl', color: 'secondary' as const };  };  const breakpoint = getBreakpoint(width);    // Calculate aspect ratio  const aspectRatio = width > 0 ? (width / height).toFixed(2) : '0';    // Calculate area  const area = (width * height).toLocaleString();  return (    <div className="space-y-4 p-4 max-w-sm mx-auto">      {/* Window Metrics */}      <div className="space-y-2">        <div className="flex items-center justify-between">          <Label className="text-sm font-medium">Window Metrics</Label>          <Badge variant={breakpoint.color} className="text-xs">            {breakpoint.name}          </Badge>        </div>                <div className="grid grid-cols-2 gap-2 text-xs">          <div className="bg-muted rounded p-2">            <span className="text-muted-foreground">Width:</span>            <div className="font-mono font-semibold">{width}px</div>          </div>          <div className="bg-muted rounded p-2">            <span className="text-muted-foreground">Height:</span>            <div className="font-mono font-semibold">{height}px</div>          </div>          <div className="bg-muted rounded p-2">            <span className="text-muted-foreground">Ratio:</span>            <div className="font-mono font-semibold">{aspectRatio}</div>          </div>          <div className="bg-muted rounded p-2">            <span className="text-muted-foreground">Area:</span>            <div className="font-mono font-semibold">{area}</div>          </div>        </div>      </div>      {/* Debounce Comparison */}      <div className="space-y-2">        <Label className="text-sm font-medium">Debounce Comparison</Label>        <div className="space-y-2">          <div className="flex justify-between items-center p-2 bg-muted rounded text-xs">            <span>Immediate:</span>            <code className="font-mono">{width} × {height}</code>          </div>          <div className="flex justify-between items-center p-2 bg-muted rounded text-xs">            <span>500ms delay:</span>            <code className="font-mono">{debouncedSize.width || 0} × {debouncedSize.height || 0}</code>          </div>        </div>      </div>      {/* Custom Debounce */}      <div className="space-y-2">        <Label className="text-sm font-medium">Custom Debounce</Label>        <div className="flex gap-2 items-center">          <Input            type="number"            value={customDelay}            onChange={(e) => setCustomDelay(parseInt(e.target.value) || 0)}            min="0"            max="2000"            step="100"            className="w-24 h-8 text-xs"          />          <span className="text-xs text-muted-foreground">ms</span>          <div className="flex gap-1 ml-auto">            <Button size="sm" onClick={() => setCustomDelay(0)} variant="outline" className="h-7 px-2 text-xs">              0            </Button>            <Button size="sm" onClick={() => setCustomDelay(250)} variant="outline" className="h-7 px-2 text-xs">              250            </Button>            <Button size="sm" onClick={() => setCustomDelay(1000)} variant="outline" className="h-7 px-2 text-xs">              1s            </Button>          </div>        </div>        <div className="p-2 bg-muted rounded text-xs">          <code className="font-mono">{customDebouncedSize.width || 0} × {customDebouncedSize.height || 0}</code>          <span className="text-muted-foreground ml-2">({customDelay}ms delay)</span>        </div>      </div>      {/* Breakpoints Status */}      <div className="space-y-2">        <Label className="text-sm font-medium">Breakpoints</Label>        <div className="grid grid-cols-3 gap-1 text-xs">          {[            { name: 'SM', value: 640 },            { name: 'MD', value: 768 },            { name: 'LG', value: 1024 },            { name: 'XL', value: 1280 },            { name: '2XL', value: 1536 }          ].map(bp => (            <div               key={bp.name}              className={`p-1.5 rounded text-center ${                width >= bp.value                   ? 'bg-green-100 dark:bg-green-900 text-green-700 dark:text-green-300'                   : 'bg-muted text-muted-foreground'              }`}            >              {bp.name}              <span className="text-[10px] block">{bp.value}+</span>            </div>          ))}        </div>      </div>      {/* Instructions */}      <div className="text-xs text-muted-foreground text-center pt-2">        Resize window to see real-time and debounced updates      </div>    </div>  );}

Comprehensive demo showing debouncing options, breakpoint detection, and responsive design context with real-time metrics.

Use Cases

This free open source React hook works well for:

Responsive components - Dynamic layouts based on viewport dimensions with Next.js and TypeScript
Media queries in JavaScript - Programmatic breakpoint handling using React state management
Canvas and visualization - Dynamic sizing for charts with shadcn/ui component integration
Mobile-first design - Viewport-aware components with Tailwind CSS responsive utilities
Performance optimization - Debounced resize handling for JavaScript-intensive applications
Dashboard layouts - Adaptive grid systems with real-time dimension awareness

API Reference

SSR Version (returns undefined initially):

useWindowSize(options: { initializeWithValue: false }): WindowSize

CSR Version (returns numbers immediately):

useWindowSize(options?: Partial<UseWindowSizeOptions<true>>): WindowSize<number>

Options

Option	Type	Default	Description
`initializeWithValue`	`boolean`	`true`	Whether to initialize with actual window dimensions (false for SSR)
`debounceDelay`	`number`	`undefined`	Debounce delay in milliseconds for resize events

Return Value

Property	Type	Description
`width`	`number \| undefined`	Current window width in pixels
`height`	`number \| undefined`	Current window height in pixels

Implementation Notes

Hook automatically detects server environment and disables initialization for SSR compatibility
Resize events are attached to window object with proper cleanup on component unmount
Debouncing uses the existing useDebounceCallback hook for consistent performance optimization
Initial dimensions are set using useIsomorphicLayoutEffect to prevent hydration mismatches
TypeScript overloads ensure type safety between SSR and CSR usage patterns
Window dimensions are captured from window.innerWidth and window.innerHeight properties

useWindowSize

Reactbadge

Reactbutton

Reactinput

Reactlabel

On this page