FlexTheme

A flexible, lightweight theming system for web applications with built-in dark mode support.

Features

• 🌓 Light/dark/system theme modes
• 🔄 Automatic system preference detection
• 💾 Persistent theme storage
• 🔌 Framework agnostic (works with React, Vue, Angular, or vanilla JS)
• 🧩 TypeScript support with full type definitions
• 🏎️ Tiny footprint (~1.3KB minified and gzipped)
• 🌐 SSR-friendly implementation
• 🧠 Simple, intuitive API

Installation

npm install flex-theme
# or
yarn add flex-theme
# or
pnpm add flex-theme

Basic Usage

import { getTheme, setTheme, toggleTheme } from 'flex-theme';

// Get the current theme ('light', 'dark', or 'system')
const currentTheme = getTheme(); 

// Set the theme
setTheme('dark');

// Toggle between light and dark
toggleTheme(); 

// Listen for theme changes
import { onThemeChange } from 'flex-theme';

// Register a listener
const unsubscribe = onThemeChange((theme) => {
  console.log(`Theme changed to: ${theme}`);
});

// Later, unsubscribe when no longer needed
unsubscribe();

React Integration

import { useFlexTheme } from 'flex-theme';

function ThemeToggle() {
  const { theme, toggleTheme } = useFlexTheme();
  
  return (
    <button onClick={toggleTheme}>
      Current theme: {theme}
    </button>
  );
}

API Reference

Core Functions

| Function | Description | |----------|-------------| | getTheme() | Returns the current theme ('light', 'dark', or 'system') | | setTheme(theme) | Sets the theme to the specified value | | toggleTheme() | Toggles between light and dark themes | | getResolvedTheme() | Returns the resolved theme ('light' or 'dark'), taking into account system preferences when set to 'system' | | onThemeChange(callback) | Registers a callback to be called when the theme changes | | offThemeChange(callback) | Removes a previously registered theme change callback |

React Hooks

| Hook | Description | |------|-------------| | useFlexTheme() | Returns an object with theme state and methods to control it | | useSystemTheme() | Returns the system's preferred theme ('light' or 'dark') | | useThemeWithStorage() | Theme hook with localStorage persistence |

Browser Support

FlexTheme works in all modern browsers (Chrome, Firefox, Safari, Edge).

License

MIT © [Teck]