---
title: "useColorMode – Browser Hook Usage & Examples"
description: "Reactive color mode (theme) with auto data persistence and flexible configuration."
canonical: https://reactuse.com/browser/usecolormode/
---
# useColorMode
Reactive color mode (theme) with auto data persistence and flexible configuration.
`useColorMode` manages multi-theme color modes by applying CSS class names or HTML attributes to a target element (default: ``) and persisting the selection to `localStorage`. It returns a tuple of the current mode string, a setter function, and a `cycle` function that rotates through the available modes. You can configure available modes, custom class name mappings, storage key, storage backend, and the DOM attribute used.
### When to Use
- Building applications with multiple themes beyond just light/dark (e.g., blue, green, sepia)
- Creating a theme selector with cycle-through functionality
- Persisting the user's color mode choice across sessions with automatic localStorage sync
### Notes
- **SSR-safe**: Returns the `defaultValue` (or `null`) during server-side rendering. No DOM or localStorage access occurs on the server. See the Tips section below for preventing flash of unstyled content.
- **Persistence**: By default, persists to `localStorage` under the key `"reactuses-color-mode"`. You can customize the storage key and backend (e.g., `sessionStorage`).
- **Related hooks**: For simple dark/light toggle, see `useDarkMode`. For detecting the system preference, see `usePreferredColorScheme`.
## New in v6.1.0
**useColorMode is the more flexible successor to useDarkMode.** Key differences:
- **useColorMode**: Supports multiple themes (light, dark, blue, green, etc.)
- **useDarkMode**: Limited to dark/light modes only, but maintains boolean API for compatibility
Both hooks now use string storage internally. Choose `useColorMode` for new projects requiring multiple themes.
## Tips
click to open
For server-side rendered applications, since it's not possible to obtain the user's color preference on the server side, there might be a flicker during the first render. To avoid this issue, you can refer to the following steps.
1. add a script before your content.
```tsx
```
2. To conveniently manage color modes in a unified way, we recommend using context to store them.
```tsx
import { useColorMode } from "@reactuses/core";
import React, { createContext, useContext } from "react";
type ThemeContext = {
theme: string | null;
setTheme: (theme: string) => void;
cycleTheme: () => void;
};
const ThemeContext = createContext(undefined);
export function ThemeProvider({ children }: { children: React.ReactNode }) {
const [theme, setTheme, cycleTheme] = useColorMode({
modes: ['light', 'dark', 'auto'],
defaultValue: 'auto',
storageKey: 'my-app-theme',
});
return (
{children}
);
}
export function useTheme() {
const context = useContext(ThemeContext);
if (context === undefined) {
throw new Error("useTheme must be used within a ThemeProvider");
}
return context;
}
```
## Usage
### Basic Usage
```tsx live
function Demo() {
const [colorMode, setColorMode, cycle] = useColorMode({
modes: ['light', 'dark'],
defaultValue: 'light',
});
return (