🌓 tailwind-dynamic-theme

Runtime Tailwind theme manager for React — switch between dark, light, or custom themes using CSS variables, without rebuilds.

tailwind-dynamic-theme is a lightweight, production-ready React library that enables dynamic theming in Tailwind CSS apps using runtime CSS variables. It's framework-friendly, zero-config, and supports persistent theme preferences with localStorage.

✨ Features

• 🎨 Dynamic theme switching (light/dark/custom)
• ⚡️ No rebuilds required — powered by CSS variables
• 🧠 Smart defaults with system preference detection
• 💾 Stores preference in localStorage
• 🪶 Lightweight: no Tailwind plugins required
• ✅ Written in TypeScript

📦 Installation

npm install tailwind-dynamic-theme

Or if testing locally:

npm link ../tailwind-dynamic-theme

🚀 Quick Start

1. Wrap your app with ThemeProvider

// main.tsx or App.tsx
import { ThemeProvider } from 'tailwind-dynamic-theme';

function App() {
  return (
    <ThemeProvider>
      <YourApp />
    </ThemeProvider>
  );
}

2. Use the useTheme hook to toggle themes

import { useTheme } from 'tailwind-dynamic-theme';

const ThemeToggle = () => {
  const { theme, setTheme } = useTheme();

  return (
    <div className="space-x-2">
      <button onClick={() => setTheme('light')}>Light</button>
      <button onClick={() => setTheme('dark')}>Dark</button>
      <p>Current: {theme}</p>
    </div>
  );
};

🎨 Define Your Themes

Create CSS files with custom properties:

light.css

:root {
  --color-bg: #ffffff;
  --color-text: #111827;
  --color-primary: #3b82f6;
}

dark.css

:root {
  --color-bg: #111827;
  --color-text: #f9fafb;
  --color-primary: #60a5fa;
}

Then serve them via public folder or CDN and reference them inside the lib config (already handled if you use default file structure).

⚙️ Tailwind Config Example

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        background: 'var(--color-bg)',
        text: 'var(--color-text)',
        primary: 'var(--color-primary)'
      }
    }
  },
  plugins: []
}

🧠 API

ThemeProvider

Wraps your app and injects context.

useTheme()

Returns:

{
  theme: string;          // current theme (light | dark | custom)
  setTheme: (theme: string) => void;
}

💾 Persistence

The selected theme is saved to localStorage under the key:

preferred-theme

📁 File Structure (recommended)

public/
├── themes/
│   ├── light.css
│   └── dark.css
src/
├── App.tsx
├── index.css
tailwind.config.js

🧪 Example Project

Check the /example directory for a working Vite + Tailwind + React setup using tailwind-dynamic-theme.

🛠 Roadmap

• Add support for dynamic custom themes
• Support SSR + hydration fallback
• Vue composable (optional)

📄 License

MIT © 2025 [Your Name]

💬 Feedback / Contributions

Pull requests and ideas welcome! Open an issue or fork the repo and start building. Let's make theming fun again 🎨