Head script
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
-
Reads the stored choice from
localStorage. A value that is not one of your themes (orsystem, when allowed) is ignored anddefaultis used. -
Resolves
systemtolightordarkwithmatchMedia('(prefers-color-scheme: dark)'). -
Applies the theme to
<html>: sets the attribute, or toggles one class per theme whenattributeisclass. This happens before the body is parsed, so the first paint is right. -
Listens for changes of
prefers-color-schemeand, while the choice issystem, re-applies the theme and dispatcheseclipse:change. -
Listens for the
storageevent on the configured key and does the same when another tab changes the choice. -
Listens for
astro:before-swapand applies the theme toevent.newDocument.documentElement, which is how ClientRouter navigation keeps the theme. -
When
colorSchemeorthemeColoris set, setscolor-schemeon<html>and<meta name="theme-color">at the same moments as the theme, including on the incoming document of a swap. See browser chrome. Without those options none of that code is in the script. -
When
forcedThemeis set, a page whose<html>(or incoming document, on a swap) hasdata-eclipse-forced="<theme>"gets that theme instead of the stored choice, and thestorageand system handlers keep it. See forced theme. A config withforcedThemeis held to a 600 B budget. -
When
valuesis set, the script writesvalues[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 withvaluesis 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.
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 for what was tested and how to get the hash.
Related: config, ClientRouter, getting started.