API Reference

ThemeProvider

The main provider component that wraps your application.

Props

Default Values

• themes: ["light", "dark"]
• defaultTheme: "system" (if enableSystem is true), otherwise "light"
• storage: "localStorage"
• storageKey: "theme"
• enableSystem: true
• enableColorScheme: true
• attribute: "class"
• disableTransitionOnChange: false

Examples

Basic usage:

<ThemeProvider>{children}</ThemeProvider>

With custom themes:

<ThemeProvider themes={["light", "dark", "purple", "blue"]}>
    {children}
</ThemeProvider>

With data attribute:

<ThemeProvider attribute="data-theme">{children}</ThemeProvider>

Disable transitions on change:

<ThemeProvider disableTransitionOnChange>{children}</ThemeProvider>

Force a specific theme:

<ThemeProvider forcedTheme="dark">{children}</ThemeProvider>

Use sessionStorage for per-tab themes:

<ThemeProvider storage="sessionStorage">{children}</ThemeProvider>

useTheme Hook

Returns theme state and controls.

Return Value

interface UseThemeProps {
    /** List of all available theme names */
    themes: string[];
    /** Forced theme name for the current page */
    forcedTheme?: string;
    /** Update the theme */
    setTheme: Dispatch<SetStateAction<string>>;
    /** Active theme name */
    theme?: string;
    /** System theme preference ("dark" or "light") */
    systemTheme?: "dark" | "light";
}

Properties

• theme - Current active theme name (undefined on server)
• setTheme - Function to update theme (accepts string or callback)
• forcedTheme - Forced theme if set, otherwise undefined
• themes - Array of all available themes (includes "system" if enabled)
• systemTheme - System preference ("dark" or "light", only if enableSystem is true)

Examples

Basic usage:

const { theme, setTheme } = useTheme();

setTheme("dark");

With callback:

const { theme, setTheme } = useTheme();

setTheme((current) => (current === "dark" ? "light" : "dark"));

Access system theme:

const { systemTheme } = useTheme();

console.log(systemTheme); // "dark" or "light"

Types

Attribute

type Attribute = `data-${string}` | "class";

The HTML attribute type that can be modified. Can be "class" or any data-* attribute.

ValueObject

interface ValueObject {
    [themeName: string]: string;
}

Mapping of theme names to HTML attribute values. Useful when you want different attribute values than theme names.

Example

<ThemeProvider
    themes={["light", "dark", "purple"]}
    value={{
        light: "light-mode",
        dark: "dark-mode",
        purple: "purple-mode",
    }}
>
    {children}
</ThemeProvider>

RSC Export

For Next.js App Router and other React Server Components frameworks, use the /rsc export:

import { ThemeProvider, useTheme } from "better-themes/rsc";

This ensures proper server component compatibility. The API is identical to the main export.