ThemeToggle
Switches between the configured light and dark color themes.
See it and copy it
Framework example
Choose Astro, React, or Elements to compare native usage against the shared visual output. Each example assumes the framework-level setup is already complete.
View ThemeToggle code
Framework usage
Switch targets to compare the adapter code. This live preview runs the Astro example. React and Elements use their own behavior APIs; complete the matching framework setup before copying an example.---
import { ThemeToggle } from '@santi020k/lumen-astro'
---
<div class="flex items-center gap-3">
<ThemeToggle controlled />
<span class="text-sm text-ink-soft">Change the site theme</span>
</div>'use client'
import { ThemeToggle, useThemeToggle } from '@santi020k/lumen-react'
export function Example() {
const { toggleTheme } = useThemeToggle()
return <ThemeToggle onClick={toggleTheme} />
}<script type="module">
import { defineLumenElements } from '@santi020k/lumen-elements/define'
defineLumenElements()
</script>
<div class="flex items-center gap-3">
<lumen-theme-toggle controlled></lumen-theme-toggle>
<span class="text-sm text-ink-soft">Change the site theme</span>
</div>Framework differences
React: Connect the button to useThemeToggle. The Astro controlled prop does not supply React behavior.
Choose your target
Add this component
Choose the package for your runtime. All adapters share the Lumen stylesheet. Use the matching registry command when you want a local wrapper for that framework.
pnpm add @santi020k/lumen-astropnpm add @santi020k/lumen-astrolumen add ThemeTogglelumen add ThemeTogglepnpm add @santi020k/lumen-reactpnpm add @santi020k/lumen-reactlumen add ThemeToggle --target reactlumen add ThemeToggle --target reactpnpm add @santi020k/lumen-elementspnpm add @santi020k/lumen-elementslumen add ThemeToggle --target elementslumen add ThemeToggle --target elementsAPI reference
Lumen-specific props and runtime attributes for the Astro primitive. Use the framework differences above and the copyable examples for React composition and Elements attributes; the public adapter types define their supported contracts.
| Attribute | Values | Default | Description |
|---|---|---|---|
| storageKey | string | "lumen-theme" | Sets the local-storage key used to persist the selected theme. |
| lightTheme, darkTheme | string | "light", "dark" | Sets the data-theme values toggled on the document element. |
| controlled | boolean | false | Disables automatic theme changes when the host application owns theme state. |
| class, className | string | "" | Merges custom classes with the generated ui-* root classes. |
| ...native attributes | HTML attributes | - | Forwards standard attributes to the root element unless the component consumes them. |
Runtime events
CustomEvents dispatched by the Astro UIPrimitives runtime for this component.
| Event | Target | Detail | When |
|---|---|---|---|
| ui:theme-change | ThemeToggle control ([data-ui-theme-toggle]) | { previousTheme?: string, storageKey: string, theme: string } | Fires after ThemeToggle applies and persists a new document theme. |