Documentation

Getting Started

Learn how to integrate reactive-switcher into your React project in minutes.

1Installation

bash

npm install reactive-switcher

2Define Your Themes

Create a themes configuration file with your color tokens. Each theme can have nested color palettes.

themes.ts

typescript

import { ThemesConfig } from 'reactive-switcher';

export const themes: ThemesConfig = {
  light: {
    name: 'light',
    type: 'light',
    colors: {
      background: '#ffffff',
      foreground: '#0f172a',
      primary: {
        DEFAULT: '#3b82f6',
        foreground: '#ffffff',
        50: '#eff6ff',
        500: '#3b82f6',
        600: '#2563eb',
      },
      secondary: {
        DEFAULT: '#64748b',
        foreground: '#ffffff',
      },
      surface: {
        50: '#f8fafc',
        100: '#f1f5f9',
        200: '#e2e8f0',
      },
    },
  },
  dark: {
    name: 'dark',
    type: 'dark',
    colors: {
      background: '#020617',
      foreground: '#f8fafc',
      primary: {
        DEFAULT: '#60a5fa',
        foreground: '#0f172a',
        // ... other shades
      },
      // ... other colors
    },
  },
};

3Wrap Your App

Add the ThemeProvider to your root layout. For Next.js, this goes in your layout.tsx file.

app/layout.tsx

tsx

import { ThemeProvider } from 'reactive-switcher';
import { themes } from './themes';

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider 
          themes={themes} 
          defaultTheme="light"
          enableStorage={true}
          enableSystem={true}
        >
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

4Use the Hook

Access theme state and controls anywhere in your app using the useTheme hook.

components/ThemeButton.tsx

tsx

'use client';
import { useTheme } from 'reactive-switcher';

export function ThemeButton() {
  const { theme, setTheme, toggleTheme, themes } = useTheme();

  return (
    <div>
      <p>Current theme: {theme}</p>
      
      {/* Switch to specific theme */}
      <button onClick={() => setTheme('dark')}>
        Dark Mode
      </button>
      
      {/* Cycle through themes */}
      <button onClick={toggleTheme}>
        Toggle Theme
      </button>
      
      {/* List all themes */}
      {themes.map(t => (
        <button key={t} onClick={() => setTheme(t)}>
          {t}
        </button>
      ))}
    </div>
  );
}

5Tailwind CSS v4 Integration

Map CSS variables to Tailwind's theme in your globals.css file.

globals.css

css

@import "tailwindcss";

@theme {
  --color-background: var(--color-background);
  --color-foreground: var(--color-foreground);
  
  --color-primary: var(--color-primary-DEFAULT);
  --color-primary-foreground: var(--color-primary-foreground);
  --color-primary-50: var(--color-primary-50);
  --color-primary-500: var(--color-primary-500);
  --color-primary-600: var(--color-primary-600);
  
  --color-surface-50: var(--color-surface-50);
  --color-surface-100: var(--color-surface-100);
  --color-surface-200: var(--color-surface-200);
}

@layer base {
  body {
    background-color: var(--color-background);
    color: var(--color-foreground);
    transition: background-color 0.3s, color 0.3s;
  }
}

API Reference

ThemeProvider Props

Prop	Type	Default	Description
themes	ThemesConfig	required	Theme configurations object
defaultTheme	string	"light"	Initial theme name
enableStorage	boolean	true	Persist theme to localStorage
enableSystem	boolean	true	Detect system color scheme
selector	string	":root"	CSS selector for scoped themes

useTheme() Returns

Property	Type	Description
theme	string	Current theme name
resolvedTheme	string	Actual theme (resolves "system")
setTheme	(name: string) => void	Set theme by name
toggleTheme	() => void	Cycle to next theme
themes	string[]	Available theme names
systemTheme	"light" \| "dark"	System preference