React useTernaryDarkMode Hook

Ever tried to implement a proper dark mode toggle in React and ended up with boolean state chaos, broken system preference detection, or missing auto mode functionality? You know the drill—manually managing light/dark state, forgetting to handle system preferences, dealing with localStorage persistence complexity, handling SSR hydration mismatches. This free open source React useTernaryDarkMode custom hook handles all that theme management complexity so you can focus on building beautiful interfaces instead of debugging mode switching edge cases in your React applications.

useTernaryDarkMode showcase

Smart ternary dark mode with system preference integration and persistent storage:

"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 {  useTernaryDarkMode,  type TernaryDarkMode,} from "@/components/ui/shadcn-io/use-ternary-dark-mode";export function UseTernaryDarkModeDemo() {  const {    isDarkMode,    ternaryDarkMode,    setTernaryDarkMode,    toggleTernaryDarkMode,  } = useTernaryDarkMode();  const handleModeChange = (mode: TernaryDarkMode) => {    setTernaryDarkMode(mode);    const modeLabels = { light: "Light", dark: "Dark", system: "System" };    const modeIcons = { light: "☀️", dark: "🌙", system: "💻" };    toast.success(`Theme changed! ${modeIcons[mode]}`, {      description: `Switched to ${modeLabels[mode]} mode`,    });  };  const handleToggle = () => {    toggleTernaryDarkMode();    toast.success("Theme toggled! 🔄", {      description: "Cycled to next theme option",    });  };  const getModeIcon = (mode: string) => {    switch (mode) {      case 'light': return '☀️';      case 'dark': return '🌙';      case 'system': return '💻';      default: return '🎨';    }  };  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">Ternary Dark Mode Demo</h3>        <p className="text-sm text-muted-foreground">Light, dark, and system themes</p>      </div>            {/* Current Theme Display */}      <div className="space-y-2">        <Label className="text-sm font-medium">Current Theme</Label>        <div className="bg-muted rounded p-2 min-h-[50px] flex items-center justify-center">          <div className="flex items-center gap-3">            <div className="text-2xl">{isDarkMode ? '🌙' : '☀️'}</div>            <div className="text-center">              <div className="text-sm font-medium">{isDarkMode ? 'Dark' : 'Light'}</div>              <Badge variant="outline" className="text-xs mt-1">                {getModeIcon(ternaryDarkMode)} {ternaryDarkMode}              </Badge>            </div>          </div>        </div>      </div>      {/* Theme Selection */}      <div className="space-y-2">        <Label className="text-sm font-medium">Theme Options</Label>        <div className="grid grid-cols-3 gap-2 h-10">          <Button            onClick={() => handleModeChange('light')}            variant={ternaryDarkMode === 'light' ? 'default' : 'outline'}            size="sm"            className="h-10 text-xs"          >            ☀️ Light          </Button>          <Button            onClick={() => handleModeChange('system')}            variant={ternaryDarkMode === 'system' ? 'default' : 'outline'}            size="sm"            className="h-10 text-xs"          >            💻 System          </Button>          <Button            onClick={() => handleModeChange('dark')}            variant={ternaryDarkMode === 'dark' ? 'default' : 'outline'}            size="sm"            className="h-10 text-xs"          >            🌙 Dark          </Button>        </div>      </div>      {/* Quick Toggle */}      <div className="space-y-2">        <Label className="text-sm font-medium">Quick Toggle</Label>        <div className="min-h-[40px] flex items-center">          <Button            onClick={handleToggle}            variant="outline"            size="sm"            className="w-full h-10"          >            🔄 Toggle Theme          </Button>        </div>      </div>      {/* Instructions */}      <div className="text-center min-h-[16px] flex items-center justify-center">        <div className="text-xs text-muted-foreground">          System mode follows your OS preference        </div>      </div>    </div>  );}export default UseTernaryDarkModeDemo;

"use client"import type { Dispatch, SetStateAction } from "react"import { useLocalStorage } from "@/components/ui/kibo-ui/use-local-storage"import { useMediaQuery } from "@/components/ui/kibo-ui/use-media-query"const COLOR_SCHEME_QUERY = "(prefers-color-scheme: dark)"const LOCAL_STORAGE_KEY = "use-ternary-dark-mode"export type TernaryDarkMode = "system" | "dark" | "light"export type TernaryDarkModeOptions = {  defaultValue?: TernaryDarkMode  localStorageKey?: string  initializeWithValue?: boolean}export type TernaryDarkModeReturn = {  isDarkMode: boolean  ternaryDarkMode: TernaryDarkMode  setTernaryDarkMode: Dispatch<SetStateAction<TernaryDarkMode>>  toggleTernaryDarkMode: () => void}export function useTernaryDarkMode({  defaultValue = "system",  localStorageKey = LOCAL_STORAGE_KEY,  initializeWithValue = true,}: TernaryDarkModeOptions = {}): TernaryDarkModeReturn {  const isDarkOS = useMediaQuery(COLOR_SCHEME_QUERY, { initializeWithValue })  const [mode, setMode] = useLocalStorage(localStorageKey, defaultValue, {    initializeWithValue,  })  const isDarkMode = mode === "dark" || (mode === "system" && isDarkOS)  const toggleTernaryDarkMode = () => {    const modes: TernaryDarkMode[] = ["light", "system", "dark"]    setMode((prevMode): TernaryDarkMode => {      const nextIndex = (modes.indexOf(prevMode) + 1) % modes.length      return modes[nextIndex]    })  }  return {    isDarkMode,    ternaryDarkMode: mode,    setTernaryDarkMode: setMode,    toggleTernaryDarkMode,  }}

This free open source React hook simplifies theme management with TypeScript support for modern JavaScript applications. Whether you're building responsive dashboards, user preference systems, or accessibility-focused interfaces in your Next.js projects, this React hook keeps your dark mode implementation reliable and user-friendly.

Installation

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

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

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

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

Why most ternary dark mode implementations suck

Look, you could keep managing theme state with useState and media queries. But then you hit the dark mode complexity—missing system preference integration, broken persistence across sessions, inconsistent state synchronization, SSR hydration issues with theme flashing in React applications.

Most developers manually manage light/dark state with boolean flags, missing the crucial "system" option that modern users expect in TypeScript components. Or they handle system preferences with manual media query listeners that break when unmounting components, causing memory leaks and stale event handlers. Some skip localStorage persistence entirely and lose user preferences on page refresh in Next.js projects.

This React hook uses optimized theme management under the hood, with automatic system preference detection and seamless localStorage integration in JavaScript applications. The browser handles all the preference events, plus you get comprehensive state management and type safety in one call.

Plus it handles all the edge cases—SSR compatibility with controlled hydration, automatic system preference synchronization, persistent storage with fallbacks, proper cleanup and memory management in React development. No more theme flashing or broken dark mode implementations.

This free open source React hook manages theme state while you focus on building features. Whether you're creating React applications, Next.js dashboards, or TypeScript components, reliable theme management keeps your JavaScript development smooth.

Features

• Ternary mode support with light, dark, and system preference detection in React applications
• System preference tracking automatically following OS dark mode settings in TypeScript components
• Persistent storage remembering user choice across browser sessions in Next.js projects
• Type-safe implementation with comprehensive TypeScript definitions and enums for JavaScript development
• SSR compatibility with proper server-side rendering support and initialization options for React frameworks
• Performance optimized using memoized callbacks and efficient event listeners in modern applications
• Free open source designed for modern React development workflows

When you'll actually use this

Real talk—this isn't for simple light/dark toggles in React applications. Basic boolean state handles binary theme switching perfectly. But when you need proper system preference integration with user override capabilities, this React hook delivers in Next.js projects.

Perfect for:

• Application themes - Provide light, dark, and auto modes for user preference built with TypeScript
• Dashboard interfaces - Let users choose themes while respecting system settings using React patterns
• Accessibility compliance - Support system-level dark mode preferences automatically in JavaScript applications
• User preference systems - Remember theme choices across browser sessions in React components
• Multi-tenant applications - Consistent theme management across different environments in Next.js applications
• Developer tools - Provide theme options that match user's development environment using TypeScript safety

API Reference

useTernaryDarkMode

useTernaryDarkMode(
  options?: TernaryDarkModeOptions
): UseTernaryDarkModeReturn

TernaryDarkModeOptions

UseTernaryDarkModeReturn

TernaryDarkMode

type TernaryDarkMode = "system" | "dark" | "light";

Common gotchas

System preference changes update automatically: When set to "system" mode, the React hook listens for OS-level dark mode changes and updates isDarkMode automatically in React applications. This behavior is intentional but means your UI will respond to system changes in real-time.

localStorage persistence is automatic: The React hook saves the user's theme choice (light/dark/system) but not the computed isDarkMode value in TypeScript components. When "system" is selected, the actual dark mode state is always computed fresh from current system preferences.

SSR requires careful initialization: Use initializeWithValue: false to prevent hydration mismatches in Next.js projects. The hook will return default values initially and update with stored preferences after client hydration.

Toggle cycles through all three modes: The toggleTernaryDarkMode function cycles: light → system → dark → light in JavaScript applications. For custom toggle behavior, use setTernaryDarkMode directly with your own logic.

System mode follows OS changes: When users have "system" selected, the theme will automatically switch if they change their OS theme settings in React frameworks. This can be unexpected if users don't understand the "system" option.

Media query listener cleanup: The React hook automatically manages media query listeners in TypeScript projects. Manual cleanup is handled when components unmount, preventing memory leaks.

Related hooks you will also like

Questions you might have