---
title: Config
description: Every option of the eclipse() integration, with types, defaults and the errors it throws.
---

```js astro.config.mjs
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.

```ts
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](/guides/browser-chrome).                                                                            |
| `themeColor`            | `Record<string, string>`            | not set             | Sets `<meta name="theme-color">` per theme. See [browser chrome](/guides/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](/guides/tailwind). |
| `headless`              | `boolean`                           | `false`             | Lets any element with `data-eclipse-set` switch the theme on click. See [headless controls](/guides/headless).                                                      |
| `forcedTheme`           | `boolean`                           | `false`             | Lets a page pin one theme with `<html data-eclipse-forced>`. See [forced theme](/guides/forced-theme).                                                              |
| `disableCssTransitions` | `boolean`                           | `false`             | Suppresses CSS transitions for the frame of a client API theme change. See [forced theme](/guides/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](/guides/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:

```js
eclipse({ themes: ['paper', 'ink'], default: 'paper' })
```

Related: [client API](/reference/client-api), [head script](/reference/head-script), [getting started](/getting-started).
