Skip to content
Astro Eclipse
Esc
↑↓navigate↵open⌘Jpreview
On this page

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 localStorage under storageKey. 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. duration and easing are not validated here: a negative or NaN duration gives an instant switch.
  • If the resulting theme equals the current one, for example system to light while 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:change is dispatched right after.
  • A second call during a running transition skips the first, and the final state matches the latest call.

Errors:

  • Throws RangeError with the message astro-eclipse: unknown theme "<name>". Known: <themes>, system. for a name that is not a preference. This includes 'system' when the themes lack light or dark.
  • Does not throw for an unknown transition name: 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.

Was this page helpful?