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 · useDarkModeEditor
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.tsfor implementation details