React useDarkMode Hook

Ever tried implementing dark mode and realized you need to handle OS preferences, localStorage sync, SSR hydration, class toggling, and media query listeners? You know the drill—check prefers-color-scheme, manage localStorage, prevent flash of wrong theme, handle SSR mismatches. This free open source React useDarkMode custom hook handles all that dark mode complexity so you can focus on your UI instead of fighting with theme persistence bugs in your React applications.

useDarkMode showcase

Complete dark mode management with OS sync:

"use client";import { toast } from "sonner";import { Button } from "@/components/ui/button";import { Badge } from "@/components/ui/badge";import { Label } from "@/components/ui/label";import { useDarkMode } from '@/components/ui/shadcn-io/use-dark-mode';export default function UseDarkModeDemo() {  const { isDarkMode, toggle, enable, disable } = useDarkMode({    localStorageKey: 'demo-basic-theme',    applyDarkClass: false  });  const handleToggle = () => {    toggle();    toast.success("Theme toggled! 🎨", {      description: `Switched to ${!isDarkMode ? "dark" : "light"} mode`,    });  };  const handleEnable = () => {    enable();    toast.success("Dark mode enabled! 🌙", {      description: "Theme preference saved to localStorage",    });  };  const handleDisable = () => {    disable();    toast.success("Light mode enabled! ☀️", {      description: "Theme preference saved to localStorage",    });  };  return (    <div className="p-6 max-w-sm mx-auto space-y-6">      {/* Header */}      <div className="text-center space-y-2">        <h3 className="text-lg font-semibold">Dark Mode Demo</h3>        <p className="text-sm text-muted-foreground">Basic useDarkMode hook functionality</p>      </div>            {/* Theme Status Display */}      <div className="text-center space-y-3">        <Label className="text-sm font-medium">Current Theme</Label>        <div className="min-h-[60px] flex items-center justify-center">          <Badge             variant={isDarkMode ? "default" : "secondary"}             className="text-2xl px-6 py-3 font-semibold"          >            {isDarkMode ? '🌙 Dark' : '☀️ Light'}          </Badge>        </div>      </div>      {/* Control Buttons - Fixed height containers to prevent layout shift */}      <div className="space-y-2">        <div className="min-h-[36px] flex items-center">          <Button            onClick={handleToggle}            variant="default"            size="sm"            className="w-full text-sm h-9"          >            Toggle Theme          </Button>        </div>                <div className="grid grid-cols-2 gap-2 min-h-[36px]">          <Button            onClick={handleEnable}            disabled={isDarkMode}            variant="outline"            size="sm"            className="text-sm h-9"          >            🌙 Dark          </Button>          <Button            onClick={handleDisable}            disabled={!isDarkMode}            variant="outline"            size="sm"            className="text-sm h-9"          >            ☀️ Light          </Button>        </div>      </div>      {/* Storage Info */}      <div className="space-y-2">        <div className="flex items-center justify-between min-h-[20px]">          <Label className="text-sm font-medium">Storage</Label>          <Badge variant="outline" className="text-xs px-2 py-0.5">            localStorage          </Badge>        </div>        <div className="bg-muted rounded p-2 min-h-[32px] flex items-center justify-center">          <code className="text-xs">            demo-basic-theme: {isDarkMode ? 'true' : 'false'}          </code>        </div>      </div>      {/* Status Display - Fixed height to prevent shift */}      <div className="text-center min-h-[20px] flex items-center justify-center">        <div className="text-xs text-muted-foreground">          Preference saved and persists across sessions        </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 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 }

This free open source React hook simplifies theme switching with TypeScript support for modern JavaScript applications. Whether you're building dashboards, documentation sites, or apps in your Next.js projects, this React hook keeps your dark mode implementation bulletproof.

Installation

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

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

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

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

Why most dark mode implementations suck

Look, you could manually check window.matchMedia, add event listeners, manage localStorage, toggle classes, and handle SSR edge cases. But after debugging the third "flash of wrong theme" bug, you'll appreciate having this handled properly.

Most developers forget about the flash of unstyled content (FOUC) in React applications. Or they ignore SSR hydration mismatches that break Next.js builds. Some handle OS preference detection but forget localStorage persistence, losing user choices on refresh.

The React hook automatically syncs with OS preferences—when users change their system theme, your app follows in TypeScript components. It persists their choice to localStorage so it remembers across sessions. Plus it handles the SSR nightmare of hydration mismatches in Next.js projects.

Real talk—dark mode seems simple until you hit the edge cases in JavaScript applications. Flash of unstyled content, SSR mismatches, OS preference changes, localStorage failures. This React hook handles all of it.

This free open source React hook handles the theme boilerplate while you focus on building features. Whether you're creating React applications, Next.js projects, or TypeScript codebases, this custom hook keeps your dark mode rock solid.

Features

• OS preference detection with automatic synchronization to system theme in React applications
• localStorage persistence for user preference across sessions with error handling for TypeScript components
• SSR-safe initialization with hydration mismatch prevention for Next.js projects
• TypeScript support with complete type definitions and IntelliSense integration
• Automatic DOM updates applying dark class to document root in JavaScript applications
• shadcn/ui integration with Tailwind CSS dark mode support for React development
• Free open source designed for modern React development workflows

When you'll actually use this

Real talk—this isn't for simple CSS-only dark mode in React applications. If you just need dark styles, use CSS media queries. But when you need user control, persistence, and JavaScript-driven theming, this React hook shines in Next.js projects.

Perfect for:

• Theme switching - User-controlled dark/light mode toggles built with TypeScript
• OS sync - Respecting and reacting to system preference changes in React components
• Persistent themes - Saving user choice across browser sessions using JavaScript storage
• SSR applications - Server-side rendering without hydration mismatches in Next.js applications
• Documentation sites - Reader-friendly theme options with TypeScript integration
• Dashboards - Professional apps with theme preferences in React development
• E-commerce - Accessible shopping experiences with theme control using React patterns
• Content platforms - Reading modes for different lighting conditions in JavaScript applications

API Reference

useDarkMode

Return Value

Common gotchas

Flash of wrong theme (FOUC) on load: The React hook tries to prevent this, but if you're not using SSR correctly or loading the hook late in React applications, you might see a flash. Initialize early in your Next.js app structure.

SSR hydration mismatches break builds: Set initializeWithValue: false for SSR to avoid hydration errors in TypeScript projects. The theme will apply after mount, which is a trade-off but prevents build failures.

localStorage can silently fail: Private browsing, storage quota, or browser settings can block localStorage in JavaScript applications. The hook handles this gracefully but won't persist across sessions.

Root class placement matters: The dark class goes on <html> or <body>, not individual components in React development. This is how Tailwind's dark mode works—make sure your CSS expects this.

Live OS preference updates: When users change their system theme, the React hook updates immediately in TypeScript components. This might surprise users who manually selected a different theme.

Performance impact with many components: Each theme change re-renders components using theme context in Next.js projects. Consider memoization for expensive theme-dependent computations.

Related hooks you will also like

Questions you might have