useColorScheme

A hook for managing the user's Color Scheme (dark mode or light mode).

Returns the current Color Scheme state and set functions for controlling it.

prefers-color-scheme may not be supported on Android versions below 10, and there are cases where Color Scheme information is provided externally (e.g., passed via UserAgent when a native app opens a webview). In such cases, defaultValue can be used.

This allows you to maintain a Color Scheme provided externally, or manage a self-contained Color Scheme policy when used standalone on the web.

state

• colorScheme: The currently applied color theme (dark, light). If a value is stored in local storage, it uses that value. If there is no stored value and defaultValue is set, it takes defaultValue first. If defaultValue is not set, it falls back to the user's preferred color scheme (prefers-color-scheme).
• preferredColorScheme: The user's preferred color theme, determined by system settings.

set

• setToggleMode: Toggles the current color theme between dark mode and light mode.
• setDarkMode: Sets the current color theme to dark mode.
• setLightMode: Sets the current color theme to light mode.
• setPreferredMode - Sets the current color theme to the user's preferred color scheme (prefers-color-scheme).

Code

🔗 View source code

Interface

typescript

interface UseColorSchemeOptions {
  defaultValue?: (() => ColorScheme) | ColorScheme;
  key?: string; // default: COLOR_SCHEME_DEFAULT_KEY: 'color-scheme'
  shouldSetBodyClass?: boolean; // default: false
}

interface UseColorSchemeReturnType {
  colorScheme: ColorScheme;
  preferredColorScheme: ColorScheme;
  setToggleMode: () => void;
  setDarkMode: () => void;
  setLightMode: () => void;
  setPreferredMode: () => void;
}

typescript

function useColorScheme({
  defaultValue,
  key,
  shouldSetBodyClass,
}: UseColorSchemeOptions = {}): UseColorSchemeReturnType;

Options

Name	Type	Default	Description
defaultValue	ColorScheme | (() => ColorScheme)	-	The default color theme to use when prefers-color-scheme is not supported or when the theme is provided externally.
key	string	'color-scheme'	The key used to store the value in local storage.
shouldSetBodyClass	boolean	false	If true, adds the current color theme as a class on document.body.

Returns

Name	Type	Description
colorScheme	ColorScheme	The currently applied color theme (dark | light).
preferredColorScheme	ColorScheme	The user's system preferred color theme.
setToggleMode	() => void	Toggles the current color theme between dark and light mode.
setDarkMode	() => void	Sets the current color theme to dark mode.
setLightMode	() => void	Sets the current color theme to light mode.
setPreferredMode	() => void	Sets the current color theme to the user's preferred color scheme (prefers-color-scheme).

Usage

typescript

const Example = () => {
  const {
    colorScheme,
    preferredColorScheme,
    setToggleMode,
    setDarkMode,
    setLightMode,
    setPreferredMode,
  } = useColorScheme({
    shouldSetBodyClass: true, // if true, adds colorScheme to the body class
  });

  return (
    <div>
      <p>colorScheme: {`${colorScheme}`}</p>
      <p>preferredColorScheme: {`${preferredColorScheme}`}</p>
      <div>
        <button onClick={setToggleMode}>Toggle mode</button>
        <button onClick={setDarkMode}>Dark mode</button>
        <button onClick={setLightMode}>Light mode</button>
        <button onClick={setPreferredMode}>Preferred mode</button>
      </div>
    </div>
  );
};

Example