Client API
setTheme, toggleTheme, getTheme, getPreference, getSystemTheme, themes, onThemeChange, defineTransition and getTransition, with signatures and error cases.
import {
setTheme,
toggleTheme,
getTheme,
getPreference,
getSystemTheme,
themes,
onThemeChange,
defineTransition,
getTransition,
} from 'astro-eclipse/client'
The module reads your resolved config through a virtual module that the integration provides, so it works only in an Astro project that has eclipse() in integrations.
Every function is safe to import and call during server rendering. On the server setTheme and toggleTheme do nothing, onThemeChange returns a no-op unsubscribe, and getPreference and getTheme answer from the config default (getTheme() returns light when the default is system, since there is no matchMedia). Call them from client scripts and event handlers.
The types ThemeChange, SetThemeOptions, Origin, Point, TransitionContext and TransitionDefinition are exported from the same entry.
setTheme
function setTheme(preference: string, options?: SetThemeOptions): void
interface SetThemeOptions {
transition?: string // default: config.transition
duration?: number // default: config.duration
easing?: string // default: 'ease-in-out'
origin?: MouseEvent | Element | { x: number; y: number } | 'center' // default: 'center'
direction?: 'up' | 'down' | 'left' | 'right' // default: 'right'; for wipe and blinds
}
Stores the choice, applies the theme and fires eclipse:change. The argument is a name from themes, or 'system' when the themes include light and dark.
Behavior:
- The choice is saved to
localStorageunderstorageKey. If storage cannot be written (private windows, blocked storage, full quota), the choice is kept in memory and wins over whatever is stored, until a write succeeds again.durationandeasingare not validated here: a negative orNaNduration gives an instant switch. - If the resulting theme equals the current one, for example
systemtolightwhile the system is light, the change is applied at once without an animation. - Otherwise it runs the transition, or switches instantly in the cases listed in transitions. The attribute or classes change inside the View Transition’s update step, and
eclipse:changeis dispatched right after. - A second call during a running transition skips the first, and the final state matches the latest call.
Errors:
- Throws
RangeErrorwith the messageastro-eclipse: unknown theme "<name>". Known: <themes>, system.for a name that is not a preference. This includes'system'when the themes lacklightordark. - Does not throw for an unknown
transitionname: the change is instant.
toggleTheme
function toggleTheme(options?: SetThemeOptions): void
Moves to the next theme in themes, wrapping at the end, starting from the applied theme (getTheme()). When the preference is system, it starts from whichever theme the system currently gives, and the result is an explicit choice. It takes the same options and throws the same errors as setTheme, though with valid config it does not throw.
getTheme
function getTheme(): string
The theme applied now. Never 'system': a system preference resolves to dark or light from prefers-color-scheme.
getPreference
function getPreference(): string
What the visitor chose: a theme name, or 'system'. Reads localStorage, falls back to the in-memory value when storage throws, and returns the config default when nothing valid is stored.
getSystemTheme
function getSystemTheme(): 'light' | 'dark'
The scheme the device prefers right now, whatever the visitor chose. getTheme() can be light while getSystemTheme() is dark. On the server, and where matchMedia is missing, it returns 'light'.
themes
const themes: readonly string[]
The configured theme names, in order. It never contains 'system', and the array is frozen. Use it to build your own control without repeating the list from astro.config.
onThemeChange
function onThemeChange(listener: (change: ThemeChange) => void): () => void
interface ThemeChange {
theme: string // applied theme, never 'system'
preference: string // what the visitor chose, may be 'system'
forced: string | undefined // the theme the page is pinned to, see the forced theme guide
}
Calls listener whenever the theme changes, and returns a function that removes the listener. It does not call the listener for the current value. Read it with getTheme() and getPreference() first.
While a page is forced, getTheme() returns the forced theme, getPreference() the stored choice, and setTheme stores without applying.
It fires for setTheme and toggleTheme, for system changes while the preference is system, and for changes made in another tab. It is a wrapper over the eclipse:change event on document.
const stop = onThemeChange(({ theme, preference, forced }) => {
console.log(theme, preference, forced)
})
stop()
defineTransition
function defineTransition(name: string, definition: TransitionDefinition): TransitionDefinition
Registers an effect and returns the definition. An existing name, built-in or not, is replaced. See custom transitions for the shape and a worked example.
getTransition
function getTransition(name: string): TransitionDefinition | undefined
Returns the registered definition for name, or undefined. Call its old and new functions with a context to get the keyframes, for example to preview an effect on an element of your own. The demo gallery does this for its preview squares.
Related: config, head script, framework islands.