$ @"

@asafarim/react-themes

A comprehensive theme management system for React applications with automatic dark/light mode detection, custom theme creation, and smooth transitions.

📸 Preview

Experience the theme system in action with our Live Interactive Demo:

• https://alisafari-it.github.io/react-themes/

🎯 Demo Showcases

The live demo demonstrates all package capabilities:

• 🎨 Theme Switching: Real-time theme transitions between light, dark, and auto modes
• 🔧 Component Gallery: All built-in components (ThemeToggle, ThemeSelector) in action
• 📱 Responsive Design: How themes adapt across different screen sizes
• 🎪 CSS Variables: Live CSS variable updates and their effects
• ⚡ Performance: Smooth animations and transitions
• ♿ Accessibility: Keyboard navigation and screen reader support

🚀 Try It Live

Visit https://alisafari-it.github.io/react-themes/ to:

1. Interactive Testing: Toggle between themes and see instant changes
2. Code Examples: View implementation examples for each feature
3. Performance Metrics: See how fast theme switching works
4. Integration Examples: Real-world usage with other components
5. Customization Demo: Examples of custom theme creation
6. Browser Compatibility: Test across different browsers and devices

✨ Features

🌓 Smart Theme Management

• Auto Detection: Follows system dark/light mode preferences
• Manual Override: Users can manually select their preferred theme mode
• Persistence: Remembers user choice across sessions (localStorage)
• Real-time Updates: Instantly responds to system theme changes

🎨 Advanced Theming System

• Built-in Themes: Professionally designed light and dark themes
• Custom Themes: Create unlimited custom themes with full control
• Theme Merging: Easily extend existing themes with custom properties
• CSS Variables: Automatic injection of CSS custom properties

⚡ Performance & UX

• Smooth Transitions: Beautiful transitions between theme changes
• Zero Flicker: Prevents flash of unstyled content during init
• Lightweight: Minimal bundle size impact (~8KB gzipped)
• Tree-shakeable: Import only what you need

🔧 Developer Experience

• TypeScript First: Full type definitions
• React 18-ready: Works with React 16.8+ (Hooks) and optimized for React 18
• Hooks API: Intuitive React hooks for theme management
• Components: Pre-built, accessible components for common use cases

🎯 Integration & Compatibility

• Framework Agnostic: Next.js, Gatsby, CRA, Vite, etc.
• CSS-in-JS Compatible: styled-components, emotion, etc.
• Tailwind Ready: Use via CSS variables
• SSR Support: Hydration-safe with sensible fallbacks

♿ Accessibility

• WCAG Friendly: High contrast, readable defaults
• Keyboard Navigation: Full keyboard support
• Screen Reader Support: Proper ARIA labels
• Reduced Motion: Respects user preferences

📦 Installation

npm install @asafarim/react-themes
# or
yarn add @asafarim/react-themes
# or
pnpm add @asafarim/react-themes

🚀 Quick Start

1) Wrap your app with ThemeProvider

import React from 'react';
import { ThemeProvider } from '@asafarim/react-themes';
import '@asafarim/react-themes/styles.css'; // Optional base styles

function App() {
  return (
    <ThemeProvider defaultMode="auto" persistMode={true}>
      <YourAppContent />
    </ThemeProvider>
  );
}

2) Use the theme in your components

import React from 'react';
import { useTheme, ThemeToggle } from '@asafarim/react-themes';

function MyComponent() {
  const { mode, currentTheme } = useTheme();

  return (
    <div style={{ background: currentTheme.colors.background, color: currentTheme.colors.text }}>
      <h1>Current mode: {mode}</h1>
      <ThemeToggle />
    </div>
  );
}

🎯 Use Cases & Examples

📚 Real-World Applications

See the demo for these practical implementations:

🌐 Web Applications

// E-commerce dashboard with theme switching
import { ThemeProvider, ThemeToggle } from '@asafarim/react-themes';

function EcommerceDashboard() {
  return (
    <ThemeProvider defaultMode="auto" persistMode={true}>
      <header className="dashboard-header">
        <h1>Sales Dashboard</h1>
        <ThemeToggle size="sm" showLabels={true} />
      </header>
      <main className="dashboard-content">{/* ... */}</main>
    </ThemeProvider>
  );
}

📱 Mobile-First Design

/* Responsive design that adapts to theme */
.mobile-card {
  background: var(--theme-color-background-secondary);
  border: 1px solid var(--theme-color-border);
  padding: var(--theme-spacing-md);
  border-radius: var(--theme-radius-lg);
  box-shadow: var(--theme-color-shadow, 0 1px 3px 0 rgba(0, 0, 0, 0.1));
  transition: var(--theme-transition-normal);
}

🎨 Design Systems

// Integration with component libraries
import { Button, Card } from 'your-ui-library';
import { useTheme } from '@asafarim/react-themes';

function ThemedComponents() {
  const { currentTheme } = useTheme();
  return (
    <Card style={{ backgroundColor: currentTheme.colors.background, color: currentTheme.colors.text }}>
      <Button variant={currentTheme.mode === 'dark' ? 'outlined' : 'filled'}>
        Themed Button
      </Button>
    </Card>
  );
}

🔄 Advanced Patterns

🎪 Dynamic Theme Loading

import { createTheme, useTheme } from '@asafarim/react-themes';

function DynamicThemeLoader() {
  const { setTheme } = useTheme();
  const loadUserTheme = async (userId: string) => {
    const resp = await fetch(`/api/users/${userId}/theme`);
    const themeData = await resp.json();
    const customTheme = createTheme(lightTheme, themeData);
    setTheme(customTheme);
  };
  return <div>Loading personalized theme...</div>;
}

🏢 Multi-Brand Applications

const brandThemes = {
  corporate: createTheme(lightTheme, { name: 'corporate', colors: { primary: '#0066cc', secondary: '#004499' } }),
  creative: createTheme(darkTheme, { name: 'creative', colors: { primary: '#ff6b6b', secondary: '#4ecdc4' } })
};

<ThemeProvider customThemes={{ ...brandThemes }}>
  <BrandSwitcher />
</ThemeProvider>

📖 API Reference

🏗️ ThemeProvider

Manages theme state and applies CSS variables throughout your app.

interface ThemeProviderProps {
  children: ReactNode;
  defaultMode?: 'light' | 'dark' | 'auto';
  defaultTheme?: string; // 'default' | custom theme name
  persistMode?: boolean; // default: true
  storageKey?: string;   // default: 'asafarim-theme-mode'
  customThemes?: Record<string, Theme>;
}

• defaultMode: Initial mode on first load
• defaultTheme: Name of the default theme to use
• persistMode: Save user's mode to localStorage
• storageKey: Key used for persistence
• customThemes: Provide additional themes

🪝 useTheme Hook

interface UseThemeReturn {
  currentTheme: Theme;
  mode: ThemeMode; // 'light' | 'dark' | 'auto'
  setMode: (mode: ThemeMode) => void;
  setTheme: (theme: Theme) => void;
  themes: Record<string, Theme>;
  toggleMode: () => void; // cycles light ↔ dark (auto flips to opposite of system)
}

⚡ useThemeToggle Hook

interface UseThemeToggleReturn {
  mode: ThemeMode;
  setMode: (mode: ThemeMode) => void;
  toggleMode: () => void;
  isDark: boolean;
  isLight: boolean;
  isAuto: boolean;
  effectiveMode: 'light' | 'dark';
}

Components

ThemeToggle

A pre-built theme toggle button with variants and icon customization.

import { ThemeToggle } from '@asafarim/react-themes';
import { Sun, Moon } from 'lucide-react';

<ThemeToggle
  size="md"                 // 'sm' | 'md' | 'lg'
  showLabels={false}
  variant="default"         // 'default' | 'outline' | 'ghost' | 'link' | 'circle' | 'icon'
  ariaLabel="Toggle theme"
  lightIcon={<Sun />}
  darkIcon={<Moon />}
  className="custom-class"
  style={{ margin: '10px' }}
/>

ThemeSelector

A dropdown selector for theme modes.

<ThemeSelector
  showLabels={true}
  className="custom-class"
  options={[
    { mode: 'light', label: 'Light', icon: '☀️' },
    { mode: 'dark', label: 'Dark', icon: '🌙' },
    { mode: 'auto', label: 'Auto', icon: '🌓' }
  ]}
/>

🎨 Custom Themes

import { createTheme, lightTheme, ThemeProvider } from '@asafarim/react-themes';

const myCustomTheme = createTheme(lightTheme, {
  name: 'my-theme',
  colors: {
    primary: '#ff6b6b',
    primaryHover: '#ff5252',
    background: '#f8f9fa',
    text: '#212529'
  }
});

<ThemeProvider customThemes={{ 'my-theme': myCustomTheme }}>
  <App />
</ThemeProvider>

Using CSS Variables

.my-component {
  background-color: var(--theme-color-background);
  color: var(--theme-color-text);
  border: 1px solid var(--theme-color-border);
  border-radius: var(--theme-radius-md);
  padding: var(--theme-spacing-md);
  transition: all var(--theme-transition-normal);
}

.my-button {
  background-color: var(--theme-color-primary);
  color: white;
  font-size: var(--theme-font-size-sm);
}

.my-button:hover {
  background-color: var(--theme-color-primary-hover);
}

🎯 Integration with @asafarim/dd-menu

import { DDMenu } from '@asafarim/dd-menu';
import { useTheme } from '@asafarim/react-themes';

function NavMenu() {
  const { mode } = useTheme();
  return (
    <DDMenu items={menuItems} theme={mode} variant="navbar" />
  );
}

🚀 Live Demo & Showcase

Experience all features at:

• https://alisafari-it.github.io/react-themes/

The demo highlights:

• Theme Gallery: Light, Dark, Auto, Custom Themes
• Component Showcase: ThemeToggle variants, ThemeSelector
• CSS Variables Live: Watch variables update in real time
• Accessibility: Keyboard, screen readers, reduced motion
• Mobile Optimizations: Touch-friendly controls and layouts

🔧 Advanced Usage

Custom Theme Structure (partial)

interface Theme {
  name: string;
  mode: 'light' | 'dark' | 'auto';
  colors: {
    background: string;
    backgroundSecondary: string;
    backgroundTertiary: string;
    text: string;
    textSecondary: string;
    textMuted: string;
    border: string;
    borderLight: string;
    borderHover: string;
    primary: string;
    primaryHover: string;
    primaryActive: string;
    hover: string;
    active: string;
    focus: string;
    shadow: string;
    shadowMd: string;
    shadowLg: string;
  };
  spacing: { xs: string; sm: string; md: string; lg: string; xl: string; '2xl': string; '3xl': string; '4xl': string };
  // ... typography, radius, transitions, zIndex
}

Programmatic Theme Application

import { applyTheme } from '@asafarim/react-themes';

applyTheme(customTheme, 'dark');

🌍 Browser Support

• Modern browsers with CSS custom properties support
• Chrome 49+
• Firefox 31+
• Safari 9.1+
• Edge 16+

🤝 Contributing

We welcome contributions! The project is open-source and actively maintained.

🛠️ Development Setup

git clone https://github.com/AliSafari-IT/react-themes.git
cd react-themes
pnpm install
pnpm build
# optional during development
pnpm dev
# quality
pnpm type-check
pnpm lint

🔬 Local Verification

# After build, you can quickly verify exports
node test-import.js

📋 Contribution Guidelines

• Follow TypeScript best practices
• Add tests (where applicable) for new features
• Update documentation and examples
• Ensure accessibility compliance
• Test across different browsers

📄 License

MIT License — see the LICENSE file for details.

🌟 Why Choose @asafarim/react-themes?

✅ Production Ready

• Used in production at ASafariM projects
• Tested across browsers and devices
• Optimized for performance and accessibility
• Regular updates and maintenance

🎯 Developer Focused

• Extensive TypeScript support
• Comprehensive documentation with live examples
• Active community support
• Regular feature updates

🚀 Modern Standards

• React 16.8+ (Hooks) and React 18 optimized
• CSS Custom Properties
• ES2020+ JavaScript features
• Modern bundling and tree-shaking support

🔗 Related Packages & Ecosystem

• @asafarim/dd-menu — Elegant dropdown menu component with theme integration

📊 Project Stats

• 🏗️ Built with: TypeScript, React, CSS Custom Properties
• 📦 Bundle Size: ~8KB gzipped
• 🌍 Browser Support: Chrome 49+, Firefox 31+, Safari 9.1+, Edge 16+
• ⚡ Performance: Zero‑flicker theme switching, optimized re‑renders
• ♿ Accessibility: WCAG 2.1 AA-friendly

📝 Changelog

v1.8.1 — Latest

• New: ThemeToggle variants (default, outline, ghost, link, circle, icon)
• New: Custom icon support via lucide-react (lightIcon/darkIcon)
• New: mergeThemes, mergeThemeColors, deepMergeThemes utilities
• Improved: TypeScript types and CSS variable coverage
• Improved: SSR behavior and localStorage persistence handling
• Docs: Unified demo links, updated examples

v1.1.0

• Enhanced TypeScript definitions
• Improved performance and bundle size
• Added comprehensive demo showcase
• Extended browser compatibility
• New theme customization options

v1.0.0 — Initial Release

• Core ThemeProvider functionality
• Auto mode detection with system preference sync
• CSS variable injection system
• Built-in components (ThemeToggle, ThemeSelector)
• TypeScript support with full type safety
• localStorage persistence with customizable keys

🌟 Experience the Future of React Theming

Try the Live Demo · View on npm · Source Code

Made with ❤️ and ☕ by ASafariM

Empowering developers to create beautiful, accessible, and user‑friendly themed applications