![\"Demo:](\"../../.github/assets/demo.gif\")
\n\n \n
Check out the Live Example to try it for yourself.
\n\n## Install\n\n```sh\nnpm install @brustack/nuxt-theme-transitions\n# or\npnpm add @brustack/nuxt-theme-transitions\n# or\nyarn add @brustack/nuxt-theme-transitions\n```\n\n```ts\n// nuxt.config.ts\nexport default defineNuxtConfig({\n modules: ['@brustack/nuxt-theme-transitions'],\n})\n```\n\nPrefer to see it running first?\n\n```sh\ngit clone https://github.com/brustack/theme-transitions.git\ncd theme-transitions\nnpm run install:nuxt-demo\nnpm run dev:nuxt-demo\n```\n\n## Usage\n\n```vue\n\n\n\n \n\n```\n\nBinding `toggleTheme` directly to `@click` works because it accepts the native `MouseEvent` and derives the spread effect's origin from the click position automatically. `originFromElement(elementRef)` is auto-imported too, use it instead if you want to animate from an element's center rather than the click position.\n\n## Styling\n\n`useThemeTransition` applies the current theme's name (`dark`, `light`, or a custom name, see Custom themes below) as a class on ``. Style your palette off that class with any approach.\n\n### CSS variables\n\n```css\n:root {\n --bg: #ffffff;\n --text: #111111;\n}\n\nhtml.dark {\n --bg: #0b0b10;\n --text: #f4f2ed;\n}\n\nhtml.sepia {\n --bg: #f4ecd8;\n --text: #4b3621;\n}\n\nbody {\n background: var(--bg);\n color: var(--text);\n}\n```\n\n### Tailwind\n\nSet `darkMode: 'class'` in your Tailwind config (see Install above), then map your color tokens to the CSS variables above:\n\n```js\n// tailwind.config.js\nmodule.exports = {\n darkMode: 'class',\n theme: {\n extend: {\n colors: {\n bg: 'var(--bg)',\n text: 'var(--text)',\n },\n },\n },\n};\n```\n\n## Configuration (optional)\n\n| Variant | `duration` | `easing` |\n|---|:---:|:---:|\n| `spread` | `'1s'` | ❌ |\n| `fade` (default) | `'400ms'` | `'ease'` |\n| `none` | ❌ | ❌ |\n\n```ts\n// nuxt.config.ts\nexport default defineNuxtConfig({\n modules: ['@brustack/nuxt-theme-transitions'],\n themeTransition: {\n variant: 'spread',\n duration: '1s',\n },\n})\n```\n\nRestart the dev server after changing `themeTransition`.\n\n`toggleTheme`/`setTheme` also accept a `MouseEvent` (as shown in Usage) or an explicit options object, e.g. `{ origin, variant, duration }`, to override the configured value for just that one call. `origin` is required for `spread`, derive it with `originFromEvent(event)` or `originFromElement(el)`.\n\n### Custom themes\n\nRegister extra theme names beyond `light`/`dark`/`system` via `themeTransition.themes`:\n\n```ts\n// nuxt.config.ts\nexport default defineNuxtConfig({\n modules: ['@brustack/nuxt-theme-transitions'],\n themeTransition: {\n themes: ['sepia', 'sunset'],\n },\n})\n```\n\n`setTheme('sepia')` then applies a `sepia` class the same way `light`/`dark` do (see Styling above). `themes` always includes `['light', 'dark', 'system', ...your custom names]` once mounted, useful for building a theme switcher. `toggleTheme()` is unaffected, it always flips between `light` and `dark`.\n\n## API\n\n| | |\n|---|---|\n| `toggleTheme(eventOrOptions?)` | Switch between light and dark |\n| `setTheme(mode, eventOrOptions?)` | Set `light`, `dark`, `system`, or a custom theme name |\n| `theme` | Current resolved theme: `'light'`, `'dark'`, or a custom theme name |\n| `mode` | Current preference: `'light'`, `'dark'`, `'system'`, or a custom theme name |\n| `isAnimating` | `true` while a transition is running |\n| `themes` | All registered theme names: `['light', 'dark', 'system', ...custom]` (built-ins only before mount) |\n| `originFromEvent(event)` | Click position for spread |\n| `originFromElement(el)` | Element center for spread |\n\n## Notes\n\n- `useThemeTransition` only creates the underlying controller after the component mounts, `theme`/`mode`/`isAnimating` start as safe defaults (`'light'`/`'system'`/`false`) via Nuxt's `useState`. This means it's safe to use in SSR/universal rendering by default, no hydration mismatch, since nothing controller-dependent renders until the client takes over.\n\n## Known issues\n\n- Chrome 150 has a regression where the `spread` effect's clip-path animation can render from the wrong position after the browser window moves between displays with different DPI/scaling. This is a Chrome bug, not something this package can work around. It's already fixed upstream and verified in Chrome Canary; the fix should reach the Stable channel in a future release. See [Chromium issue #535696703](https://issues.chromium.org/issues/535696703).","readmeFilename":"README.md"}