BrowserBeginnerSSR-safehooks/browser/useDarkMode.ts

useDarkMode

light / dark / system with storage.

Import

TypeScript
import { useDarkMode } from '@/hooks';

API

Signature

useDarkMode(options?) → { isDark, preference, setPreference, toggle }

When to use

App-wide theme with system preference + storage.

SSR / Next.js

Returns defaults on the server; hydrates on the client.

Live playground

Edit the example and see it run against the real @/hooks package in this app.

Live playgroundEdit · run with real @/hooks · useDarkMode
Editor
function ThemeToggle() {
  const { isDark, preference, setPreference, toggle } = useDarkMode({
    storageKey: 'theme',
  });

  return (
    <div>
      <p>{isDark ? 'Dark' : 'Light'} ({preference})</p>
      <button onClick={toggle}>Toggle</button>
      <button onClick={() => setPreference('system')}>System</button>
    </div>
  );
}
Preview

Implementation source

Full library source for useDarkMode — copy into your project when you are not installing a package yet.

hooks/browser/useDarkMode.ts
import { useCallback, useEffect } from 'react';
import { useMediaQuery } from './useMediaQuery';
import { useLocalStorage } from '../storage/useLocalStorage';
import { isBrowser } from '../utility/isBrowser';

export type DarkModePreference = 'light' | 'dark' | 'system';

export interface UseDarkModeOptions {
  storageKey?: string;
  defaultValue?: DarkModePreference;
  classNameDark?: string;
  classNameLight?: string;
  element?: HTMLElement | null;
}

export interface UseDarkModeReturn {
  isDark: boolean;
  preference: DarkModePreference;
  setPreference: (value: DarkModePreference) => void;
  toggle: () => void;
}

/**
 * Dark mode with optional localStorage persistence and system preference.
 * Does not force a class strategy; apply `isDark` yourself or pass class names.
 */
export function useDarkMode(options: UseDarkModeOptions = {}): UseDarkModeReturn {
  const {
    storageKey = 'color-scheme',
    defaultValue = 'system',
    classNameDark = 'dark',
    classNameLight = 'light',
    element,
  } = options;

  const systemDark = useMediaQuery('(prefers-color-scheme: dark)');
  const [preference, setPreference] = useLocalStorage<DarkModePreference>(
    storageKey,
    defaultValue,
  );

  const isDark =
    preference === 'system' ? systemDark : preference === 'dark';

  // Also set color-scheme for native form controls
  useEffect(() => {
    if (!isBrowser()) return;
    const el = element ?? document.documentElement;
    el.classList.toggle(classNameDark, isDark);
    el.classList.toggle(classNameLight, !isDark);
    el.style.colorScheme = isDark ? 'dark' : 'light';
  }, [isDark, classNameDark, classNameLight, element]);

  const toggle = useCallback(() => {
    setPreference(isDark ? 'light' : 'dark');
  }, [isDark, setPreference]);

  return { isDark, preference, setPreference, toggle };
}

Copy-paste example

useDarkMode.example.tsx
'use client';

import { useDarkMode } from '@/hooks';

export function ThemeToggle() {
  const { isDark, preference, setPreference, toggle } = useDarkMode({
    storageKey: 'theme',
  });

  return (
    <div>
      <p>{isDark ? 'Dark' : 'Light'} ({preference})</p>
      <button onClick={toggle}>Toggle</button>
      <button onClick={() => setPreference('system')}>System</button>
    </div>
  );
}

Production checklist

  • Called only from Client Components or other custom hooks
  • Type parameters filled in (e.g. useFetch<User[]>)
  • Tip: Values are safe during SSR (defaults). Gate layout-dependent UI with useMounted when needed.
  • Source of truth: open hooks/browser/useDarkMode.ts for implementation details