@surajj22/theme-toggle

Lightweight, zero-dependency dark/light theme toggle for the web — with smooth transitions and automatic persistence.

Why this one?

• Tiny API — three functions, that's it.
• Smooth transitions — no jarring flash when switching themes.
• Remembers the choice — saved to localStorage, restored on next visit.
• Respects system preference — falls back to the user's OS dark/light setting if they haven't picked one yet.
• Framework-agnostic — works with plain JS, React, Vue, Svelte, anything.

Install

npm install @surajj22/theme-toggle

Usage

import { initTheme, toggleTheme, setTheme, getTheme, onThemeChange } from '@surajj22/theme-toggle';

// Call once when your app loads
initTheme();

// Toggle on a button click
document.getElementById('theme-btn').addEventListener('click', () => {
  toggleTheme();
});

// Or set a specific theme
setTheme('dark');

// Read the current theme
console.log(getTheme()); // "dark" or "light"

// React to theme changes anywhere in your app
onThemeChange((theme) => {
  console.log('Theme changed to', theme);
});

CSS

The library sets a data-theme attribute on <html>. Style your app with it:

:root[data-theme='light'] {
  --bg: #ffffff;
  --text: #111111;
}

:root[data-theme='dark'] {
  --bg: #111111;
  --text: #ffffff;
}

body {
  background: var(--bg);
  color: var(--text);
}

/* Smooth transition applied automatically by the library */
.theme-toggle-transitioning,
.theme-toggle-transitioning * {
  transition: background-color var(--theme-toggle-transition, 200ms) ease,
    color var(--theme-toggle-transition, 200ms) ease !important;
}

API

| Function | Description | |---|---| | initTheme(options?) | Call once on load. Restores saved theme or falls back to system preference. | | getTheme() | Returns the current theme ('light' or 'dark'). | | setTheme(theme, options?) | Sets a specific theme and persists it. | | toggleTheme(options?) | Switches between light and dark. | | onThemeChange(callback) | Subscribes to theme changes. Returns an unsubscribe function. |

Options

| Option | Default | Description | |---|---|---| | attribute | 'data-theme' | The HTML attribute used to mark the active theme. | | smooth | true | Whether to apply the transition class during a switch. | | transitionDuration | 200 | Transition duration in milliseconds. | | defaultTheme | system preference | Theme to use on first visit if nothing is stored. |

Running tests

npm test

Building

npm run build

Author

Suraj Jagtap

License

MIT