---
title: SSR and storage
description: What the server knows about the theme, how the page avoids a flash, and what to expect with cookie and localStorage storage.
---

The module does no server work in color-mode mode. What the server and the first paint show depends on how the theme is stored.

## Color-mode with cookie storage

With cookie storage, the server knows the visitor's `preference`, but color-mode does not resolve `value` on the server: it stays at the configured default (`'system'` unless you changed it) until the browser has run. `usePenumbra().theme` therefore answers with the preference while it names a theme, and with the first light theme while the preference is `system`. The server cannot tell whether a `system` visitor sees light or dark.

The `<html>` class is set by color-mode's inline head script before first paint. There is no flash; the e2e test `behaviour.spec.ts` in the color-mode playground records every class change on `<html>` and finds no light class with a dark cookie.

`usePenumbra().theme` is never `'system'`. While color-mode still reports `'system'`, it returns the visitor's choice when that is a concrete theme, and otherwise `light` (or the first theme in the list if `light` is not one of them).

## Color-mode with localStorage storage

With `localStorage` storage, the server cannot read the choice. It renders the fallback, and color-mode's inline script fixes the `<html>` class before paint, so the page itself does not flash.

Anything rendered from the theme can still differ between server and client. Hydration text that depends on the theme may mismatch. `PenumbraToggle` avoids this by waiting for mount before it shows its live label. If you render theme-dependent text yourself, do the same: show a neutral placeholder until `onMounted`, or use `<ClientOnly>`.

This combination has not been tested with the module. It is listed as unverified under [browser support and compatibility](/guides/browser-support#compatibility).

## Standalone mode

The store keeps the choice in `localStorage` only. The server renders the `default` (the `light` state if `default` is `'system'`), the head script applies the real theme before paint, and the store adopts it after hydration. The same label rule applies. See [standalone mode](/guides/standalone).

## Initial writes are not animated

In color-mode mode the module starts watching `preference` after hydration, one tick after `app:mounted`. The writes color-mode makes while it reads the stored value are therefore applied without an animation.

## Not tested

`ssr: false`, `nuxt generate`, and `localStorage` color-mode storage with SSR have not been run. Treat them as unverified.
