Config
Every option of the eclipse() integration, with types, defaults and the errors it throws.
import { defineConfig } from 'astro/config'
import eclipse from 'astro-eclipse'
export default defineConfig({
integrations: [
eclipse({
themes: ['light', 'dark'],
default: 'system',
attribute: 'data-theme',
storageKey: 'eclipse-theme',
transition: 'circle',
duration: 500,
// colorScheme and themeColor are off unless you set them
}),
],
})
Every option is optional. The values above are the defaults.
interface EclipseOptions {
themes?: string[]
default?: string
attribute?: 'class' | `data-${string}`
storageKey?: string
transition?: string
duration?: number
colorScheme?: Record<string, 'light' | 'dark'>
themeColor?: Record<string, string>
values?: Record<string, string>
headless?: boolean
forcedTheme?: boolean
disableCssTransitions?: boolean
}
Options
| Option | Type | Default | Description |
|---|---|---|---|
themes |
string[] |
['light', 'dark'] |
Theme names. Each is a value of attribute, or a class. toggleTheme() cycles them in this order. |
default |
string |
'system' |
The theme used before the visitor chooses. 'system' follows prefers-color-scheme and needs the themes light and dark. |
attribute |
'class' or `data-${string}` |
'data-theme' |
'class' toggles a class per theme on <html>. A data-* name sets that attribute. |
storageKey |
string |
'eclipse-theme' |
The localStorage key that holds the visitor’s choice. |
transition |
string |
'circle' |
The effect used when a call does not name one. |
duration |
number |
500 |
Effect length in milliseconds. 0 turns the animation off. |
colorScheme |
Record<string, 'light' | 'dark'> |
not set | Sets color-scheme on <html> per theme. See browser chrome. |
themeColor |
Record<string, string> |
not set | Sets <meta name="theme-color"> per theme. See browser chrome. |
values |
Record<string, string> |
not set | DOM value per theme, e.g. { dark: 'theme-dark' }; in class mode, space-separated classes. Storage and the API keep theme names. See Tailwind. |
headless |
boolean |
false |
Lets any element with data-eclipse-set switch the theme on click. See headless controls. |
forcedTheme |
boolean |
false |
Lets a page pin one theme with <html data-eclipse-forced>. See forced theme. |
disableCssTransitions |
boolean |
false |
Suppresses CSS transitions for the frame of a client API theme change. See forced theme. |
The value is also checked when the config loads, so a plain JavaScript config gets the same error.
Details
- Theme names may use letters, digits and dashes and must start with a letter.
systemis reserved. attributedata-*names must be lowercase letters, digits and dashes afterdata-.defaultother thansystemmust be one ofthemes.transitionis not validated against the registered effects. An unknown name makes every theme change instant. See transitions.colorSchemeandthemeColorkeys must be inthemes. Values ofcolorSchemearelightordark; values ofthemeColorare non-empty and cannot contain<.durationis the default forsetThemeandtoggleTheme; either can override it per call.- Changing
themes,attributeorstorageKeyafter visitors have stored a choice: a stored value that is not inthemesis ignored anddefaultis used.
Validation errors
An invalid config throws while Astro loads the config, before the build or dev server starts.
| Condition | Error message |
|---|---|
themes: [] |
astro-eclipse: `themes` needs at least one theme. |
| Invalid theme name | astro-eclipse: invalid theme name "<name>". Use letters, digits and dashes, starting with a letter. |
A theme named system |
astro-eclipse: "system" is reserved and cannot be a theme name. |
| Repeated theme | astro-eclipse: `themes` contains duplicates. |
default: 'system' without light and dark |
astro-eclipse: `default: "system"` needs the themes "light" and "dark". |
default not in themes |
astro-eclipse: `default` "<value>" is not in `themes`. |
Invalid attribute |
astro-eclipse: `attribute` must be "class" or "data-*", got "<value>". |
storageKey: '' |
astro-eclipse: `storageKey` cannot be empty. |
duration negative, NaN or infinite |
astro-eclipse: `duration` must be a number of milliseconds, 0 or more. |
values key not in themes |
astro-eclipse: `values` key "<key>" is not in `themes`. |
values.<theme> empty or with quotes, < |
astro-eclipse: `values.<theme>` must be a non-empty string of space-separated tokens without quotes or "<". |
headless not true or false |
astro-eclipse: `headless` must be true or false. |
forcedTheme not true or false |
astro-eclipse: `forcedTheme` must be true or false. |
disableCssTransitions not true or false |
astro-eclipse: `disableCssTransitions` must be true or false. |
A set of themes without light and dark must set default to one of them, because the default is system otherwise:
eclipse({ themes: ['paper', 'ink'], default: 'paper' })
Related: client API, head script, getting started.