ThemeToggle
A ready-made button that cycles themes, with an accessible name that says where it will go.
ThemeToggle is an Astro component with no palette and almost no styling. It renders a real <button>, cycles the themes you give it, and starts the reveal at the point where it was clicked.
---
import { ThemeToggle } from 'astro-eclipse/components'
---
<ThemeToggle />
<ThemeToggle themes={['light', 'dark']} transition="wipe" direction="down" />
Props
| Prop | Type | Default | Notes |
|---|---|---|---|
themes |
string[] |
every theme in config | The cycle, in order. Names must be in themes. |
transition |
string |
the config’s transition |
Any built-in or defineTransition() name. |
duration |
number |
the config’s duration |
Milliseconds. |
direction |
'up' | 'down' | 'left' | 'right' |
'right' |
For wipe and blinds. |
label |
string |
Theme: {current}. Switch to {next} |
The accessible name. {current} and {next} become theme names. |
class |
string |
none | Added next to the eclipse-toggle class. |
Any other attribute (id, aria-*, data-*) is passed to the button. themes must be a non-empty subset of the configured themes and cannot contain system; a wrong value fails the build with a clear message. The default slot replaces the icon. The built-in icon is a half-filled circle that uses currentColor.
Need a direct pick among themes, or a System option? Use ThemeSelect.
Accessible name
The button has no visible text, so its aria-label carries the meaning. Once the page loads it reads Theme: dark. Switch to sepia, and it is updated whenever the theme changes, including changes from other tabs, from system mode and from other buttons. Before the script runs it reads Switch theme. If you put visible text in the slot, the button keeps that text as its name and the aria-label is removed, so the visible and accessible names match. Translate the name with the label prop.
Nothing is announced when the theme changes. See accessibility if your site wants a live region.
Styling
The component ships low-specificity rules (:where(.eclipse-toggle)), so any selector of yours wins. In forced-colors mode it uses ButtonText, ButtonFace and Highlight, and gets a border so the button stays visible.
ClientRouter
One click listener on document serves every toggle on the page, so buttons that arrive with a navigation work without rebinding. The labels are refreshed on astro:page-load.
Not checked
The component is tested in Chromium and WebKit (keyboard, accessible name, navigation, axe in light and dark). Firefox runs in CI but has not been run by hand, and forced-colors mode is not checked.