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

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. system is reserved.
  • attribute data-* names must be lowercase letters, digits and dashes after data-.
  • default other than system must be one of themes.
  • transition is not validated against the registered effects. An unknown name makes every theme change instant. See transitions.
  • colorScheme and themeColor keys must be in themes. Values of colorScheme are light or dark; values of themeColor are non-empty and cannot contain <.
  • duration is the default for setTheme and toggleTheme; either can override it per call.
  • Changing themes, attribute or storageKey after visitors have stored a choice: a stored value that is not in themes is ignored and default is 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.

Was this page helpful?