---
title: Head script
description: What the inline script injected into every page does, how big it is and how it handles storage failure.
---

The integration injects one inline `<script>` into the `<head>` of every page. It is written by hand, runs before first paint and has no dependencies. With the default config it is about 480 B gzipped.

The size is checked on every library build by size-limit, against a budget of 700 B for the default config and 1 kB for a config with `colorScheme` and `themeColor`. Other configs differ by the length of their theme names and storage key.

## What it does

1. Reads the stored choice from `localStorage`. A value that is not one of your themes (or `system`, when allowed) is ignored and `default` is used.
2. Resolves `system` to `light` or `dark` with `matchMedia('(prefers-color-scheme: dark)')`.
3. Applies the theme to `<html>`: sets the attribute, or toggles one class per theme when `attribute` is `class`. This happens before the body is parsed, so the first paint is right.
4. Listens for changes of `prefers-color-scheme` and, while the choice is `system`, re-applies the theme and dispatches `eclipse:change`.
5. Listens for the `storage` event on the configured key and does the same when another tab changes the choice.
6. Listens for `astro:before-swap` and applies the theme to `event.newDocument.documentElement`, which is how [ClientRouter](/guides/clientrouter) navigation keeps the theme.

7. When `colorScheme` or `themeColor` is set, sets `color-scheme` on `<html>` and `<meta name="theme-color">` at the same moments as the theme, including on the incoming document of a swap. See [browser chrome](/guides/browser-chrome). Without those options none of that code is in the script.
8. When `forcedTheme` is set, a page whose `<html>` (or incoming document, on a swap) has `data-eclipse-forced="<theme>"` gets that theme instead of the stored choice, and the `storage` and system handlers keep it. See [forced theme](/guides/forced-theme). A config with `forcedTheme` is held to a 600 B budget.
9. When `values` is set, the script writes `values[theme]` instead of the theme name, and in class mode removes the classes of every theme before adding the new ones. It also reads the current theme back from a mapped value when storage cannot be read, preferring the theme with the most classes in common. A config with `values` is held to a 650 B budget.

The `eclipse:change` event is dispatched on `document` with `detail: { theme, preference }` (with `forced` added when `forcedTheme` is on). It is the same event `onThemeChange` listens to.

The script never runs an animation. The View Transition belongs to `setTheme`, which is part of the [client API](/reference/client-api).

## When storage fails

Reading `localStorage` is wrapped in a `try`. In a private window or with storage blocked, the read throws, nothing is stored, and the script falls back to `default`. If `default` is `system`, the page follows the system preference and keeps following it.

When storage cannot be read, the theme already on the page is treated as the choice, so it survives `ClientRouter` swaps. The client API keeps a choice it could not save in memory until a write works again. Other-tab sync does not work without storage, because no `storage` event is fired. A `storage` event with no key (another tab called `localStorage.clear()`) re-applies the theme too.

## Configured values are inlined

The theme names, default, attribute, key and whether `system` is allowed are written into the script as JSON from your config, with `<` escaped. It does not read the config at runtime.

## Content security policy

Because the script is inline, a strict `script-src` without `'unsafe-inline'` blocks it unless you allow it with a hash. Astro's own CSP support includes it. See the [content security policy guide](/guides/csp) for what was tested and how to get the hash.

Related: [config](/reference/config), [ClientRouter](/guides/clientrouter), [getting started](/getting-started).
