@theme-ui/color-modes

The @theme-ui/color-modes package provides utilities for managing color modes in Theme UI applications. It handles color mode state, localStorage persistence, and system preference detection.

Installation

npm install @theme-ui/color-modes @emotion/react

This package is included in the main theme-ui package and generally should not be used on its own. It’s automatically imported when you use theme-ui.

When to Use

This package is used internally by Theme UI. You would only install it directly if you’re:

Building a custom Theme UI setup
Using @theme-ui/core without the full theme-ui package
Need fine-grained control over color mode behavior

For most use cases, use the theme-ui package which includes this package.

Exports

Components

`ColorModeProvider`

A React component that provides color mode functionality to your application.

import { ThemeProvider } from '@theme-ui/core'
import { ColorModeProvider } from '@theme-ui/color-modes'

function App({ children }) {
  return (
    <ThemeProvider theme={theme}>
      <ColorModeProvider>
        {children}
      </ColorModeProvider>
    </ThemeProvider>
  )
}

Features:

Manages color mode state
Persists selection to localStorage
Syncs with system color scheme preferences
Applies color mode colors to theme
Generates CSS custom properties for color modes

Props:

children: React.ReactNode - Child components

`InitializeColorMode`

A script component that prevents flash of unstyled content (FOUC) when loading the page.

import { InitializeColorMode } from '@theme-ui/color-modes'

function Document() {
  return (
    <html>
      <head>
        <InitializeColorMode />
      </head>
      <body>
        <App />
      </body>
    </html>
  )
}

This component injects a small script that:

Reads the color mode from localStorage
Applies it to the document before React hydrates
Prevents flashing between color modes on page load

Hooks

`useColorMode`

A React hook to access and control the current color mode.

import { useColorMode } from '@theme-ui/color-modes'

function ThemeToggle() {
  const [colorMode, setColorMode] = useColorMode()
  
  return (
    <button
      onClick={() => {
        setColorMode(colorMode === 'light' ? 'dark' : 'light')
      }}
    >
      Toggle {colorMode === 'light' ? 'Dark' : 'Light'} Mode
    </button>
  )
}

Returns:

[
  colorMode: string,
  setColorMode: Dispatch<SetStateAction<string>>
]

TypeScript:

// You can specify a narrower type for color mode names
const [colorMode, setColorMode] = useColorMode<'light' | 'dark'>()

Error: Throws an error if used outside of a ColorModeProvider.

Context Extensions

The package extends the Theme UI context with color mode properties:

interface ThemeUIContextValue {
  colorMode?: string
  setColorMode?: (colorMode: SetStateAction<string | undefined>) => void
}

Access these through useThemeUI() from @theme-ui/core:

import { useThemeUI } from '@theme-ui/core'

function MyComponent() {
  const { colorMode, setColorMode } = useThemeUI()
  // ...
}

Configuration

Configure color modes in your theme:

const theme = {
  // Define your base colors (light mode by default)
  colors: {
    text: '#000',
    background: '#fff',
    primary: '#07c',
    
    // Define alternate color modes
    modes: {
      dark: {
        text: '#fff',
        background: '#000',
        primary: '#0cf',
      },
      // Add more modes as needed
      sepia: {
        text: '#433422',
        background: '#f5deb3',
        primary: '#b8860b',
      },
    },
  },
  
  // Optional: Configure color mode behavior
  config: {
    // The name of the initial/default color mode
    initialColorModeName: 'light',
    
    // Use CSS custom properties for colors
    useCustomProperties: true,
    
    // Store color mode preference in localStorage
    useLocalStorage: true,
    
    // Follow system color scheme preference
    // 'system' - always follow system preference
    // true - use system preference as initial value
    // false - don't use system preference
    useColorSchemeMediaQuery: true,
  },
}

Features

localStorage Persistence

By default, color mode selection is persisted to localStorage:

// Automatically stored when color mode changes
setColorMode('dark')

// Disable with:
const theme = {
  config: {
    useLocalStorage: false,
  },
}

System Preference Detection

Automatically detect and follow system color scheme:

const theme = {
  config: {
    // Use system preference as initial value
    useColorSchemeMediaQuery: true,
    
    // Or always follow system preference (dynamic)
    useColorSchemeMediaQuery: 'system',
  },
}

CSS Custom Properties

Colors are converted to CSS custom properties for efficient switching:

:root {
  --theme-ui-colors-text: #000;
  --theme-ui-colors-background: #fff;
  --theme-ui-colors-primary: #07c;
}

[data-theme="dark"] {
  --theme-ui-colors-text: #fff;
  --theme-ui-colors-background: #000;
  --theme-ui-colors-primary: #0cf;
}

Disable with:

const theme = {
  config: {
    useCustomProperties: false,
  },
}

Multiple Color Modes

Support more than just light and dark:

const theme = {
  colors: {
    text: '#000',
    background: '#fff',
    modes: {
      dark: { /* ... */ },
      sepia: { /* ... */ },
      highContrast: { /* ... */ },
    },
  },
}

// Switch between them:
setColorMode('sepia')
setColorMode('highContrast')

Nested Color Modes

Nested ColorModeProvider components are supported for section-specific color modes.

Implementation Details

Storage Key

Color mode is stored in localStorage under the key:

'theme-ui-color-mode'

Media Queries

The package uses these media queries for system preference:

'(prefers-color-scheme: dark)'
'(prefers-color-scheme: light)'

FOUC Prevention

The InitializeColorMode component injects this script:

(function() { 
  try {
    var mode = localStorage.getItem('theme-ui-color-mode');
    if (!mode) return
    document.documentElement.classList.add('theme-ui-' + mode);
  } catch (e) {} 
})();

This runs before React hydration to apply the correct color mode immediately.

TypeScript Types

import type {
  ColorMode,
  ColorModesScale,
} from '@theme-ui/color-modes'

// Or from @theme-ui/css:
import type { ColorMode, ColorModesScale } from '@theme-ui/css'

Notes

Requires @theme-ui/core and @theme-ui/css as dependencies
Requires @emotion/react and React 18+ as peer dependencies
No side effects - safe for tree-shaking
Supports server-side rendering with FOUC prevention
Works with nested theme providers

Examples

Basic Toggle

import { useColorMode } from '@theme-ui/color-modes'

function ColorModeToggle() {
  const [colorMode, setColorMode] = useColorMode()
  
  return (
    <button onClick={() => setColorMode(colorMode === 'default' ? 'dark' : 'default')}>
      {colorMode === 'default' ? 'Dark' : 'Light'}
    </button>
  )
}

Multiple Mode Selector

import { useColorMode } from '@theme-ui/color-modes'

function ColorModeSelector() {
  const [colorMode, setColorMode] = useColorMode()
  
  return (
    <select value={colorMode} onChange={e => setColorMode(e.target.value)}>
      <option value="light">Light</option>
      <option value="dark">Dark</option>
      <option value="sepia">Sepia</option>
    </select>
  )
}

With Icon

import { useColorMode, IconButton } from 'theme-ui'

function ColorModeButton() {
  const [colorMode, setColorMode] = useColorMode()
  
  return (
    <IconButton
      onClick={() => setColorMode(colorMode === 'light' ? 'dark' : 'light')}
      aria-label="Toggle color mode"
    >
      {colorMode === 'light' ? '🌙' : '☀️'}
    </IconButton>
  )
}

@theme-ui/core - Core Theme UI functionality
Color Modes guide - Full color modes documentation
Theming - Theme configuration

Core

Styling

Color Modes

Components

Packages

@theme-ui/color-modes

Installation

When to Use

Exports

Components

`ColorModeProvider`

`InitializeColorMode`

Hooks

`useColorMode`

Context Extensions

Configuration

Features

localStorage Persistence

System Preference Detection

CSS Custom Properties

Multiple Color Modes

Nested Color Modes

Implementation Details

Storage Key

Media Queries

FOUC Prevention

TypeScript Types

Notes

Examples

Basic Toggle

Multiple Mode Selector

With Icon

​Installation

​When to Use

​Exports

​Components

​ColorModeProvider

​InitializeColorMode

​Hooks

​useColorMode

​Context Extensions

​Configuration

​Features

​localStorage Persistence

​System Preference Detection

​CSS Custom Properties

​Multiple Color Modes

​Nested Color Modes

​Implementation Details

​Storage Key

​Media Queries

​FOUC Prevention

​TypeScript Types

​Notes

​Examples

​Basic Toggle

​Multiple Mode Selector

​With Icon

​Related

Installation

When to Use

Exports

Components

`ColorModeProvider`

`InitializeColorMode`

Hooks

`useColorMode`

Context Extensions

Configuration

Features

localStorage Persistence

System Preference Detection

CSS Custom Properties

Multiple Color Modes

Nested Color Modes

Implementation Details

Storage Key

Media Queries

FOUC Prevention

TypeScript Types

Notes

Examples

Basic Toggle

Multiple Mode Selector

With Icon

Related