Reference

Theme

Initialize the color theme before paint and add a switch that follows system or saved preferences.

Theme initialization and a control for choosing light or dark mode. Both components work together; colors are defined in Tailwind.

Availability and placement

Optional installer selection: themes. Add it later with npx @samline/astro add themes from the generated project. The installer includes src/components/Theme, src/config/theme.ts, the browser types and the themes dictionary domain, and composes Init into Main.

Complete section example

When this feature is selected, src/layouts/Main.astro mounts Init.astro in the head. It applies the theme before first paint and exposes the client API. Do not mount it again in each section.

Put this example in src/sections/ThemeControls/index.astro and render that section inside Main. Place the switch wherever the project needs the control. The optional starter demo places one instance in src/sections/DemoHeader when both welcome and themes are selected during creation:

---
import ThemeSwitch from '@/components/Theme/Switch.astro'
---

<div class='rounded-lg bg-white p-6 text-black dark:bg-black dark:text-white'>
  <ThemeSwitch class='text-accent dark:text-accent-light' />
</div>

Expected result: a translated Dark mode switch whose track and aria-checked follow the effective theme. Clicking it changes the local example surface and any other dark: styles, and persists the choice. The switch remains hidden when JavaScript or Init is absent. Merely copying Switch does not initialize themes.

Switch accepts native button attributes, classes, and a slot for an alternative translated label. It controls type, role, aria-checked, and hidden. The default label is themes.darkMode, resolved with Astro.currentLocale. The slot should contain a label, without nested interactive controls.

All instances stay synchronized. Aria-checked reflects whether the effective theme is dark, including when the preference follows the system. Clicking the switch selects an explicit light or dark preference.

Configuration

src/config/theme.ts contains behavior only:

OptionDefaultPurpose
defaultPreference'system''system', 'light', or 'dark' when no valid saved preference exists.
storageKey'site:theme'LocalStorage key for the preference.

Theme and ThemePreference types are exported from that file. Color tokens and variants live in src/styles/tailwind.css.

Client API

After Init runs, use window.siteTheme from client scripts. The property is optional in TypeScript and does not exist on the server.

MethodReturnsPurpose
getTheme()'light' | 'dark'Current effective theme.
getPreference()'light' | 'dark' | 'system'Saved or default preference.
setPreference(value)voidSaves the preference and updates the document and controls.
refresh()voidReapplies current state and synchronizes newly added controls.
window.siteTheme?.setPreference('dark')
window.siteTheme?.setPreference('light')
window.siteTheme?.setPreference('system')

const theme = window.siteTheme?.getTheme()
const preference = window.siteTheme?.getPreference()

Use system to follow the operating system again; the API persists that explicit preference. There is no need to edit localStorage directly. Invalid values are ignored at runtime.

Event

themechange is dispatched on window whenever the theme is applied. event.detail contains theme and preference; it is typed in src/types/theme.d.ts.

window.addEventListener('themechange', (event) => {
  const { theme, preference } = event.detail
  // Synchronize an existing client integration using theme and preference.
})

Use the getters for the initial state too: the first event may fire before your listener is registered. Refresh also emits the event; do not call it from a themechange listener.

Using Tailwind

<div class='bg-white text-black dark:bg-black dark:text-white'>
  <slot />
</div>

Variants follow html’s data-theme attribute rather than consulting the system directly. Welcome demonstrates light:text-black dark:text-white; the demo header uses dark:brightness-0 dark:invert for its logo.

Persistence and navigation

The preference persists in localStorage, synchronizes across tabs, and follows system changes while set to system. If storage is blocked, it works in memory. Init avoids duplicate listeners and supports Astro lifecycle events if the project adds ClientRouter. It does not add that router.

Without JavaScript, Switch is hidden. The fixed default theme remains, or light mode when the default is system.

Custom layouts and Astro ownership

If you replace Main, import @/components/Theme/Init.astro in that layout and mount <ThemeInit /> once in its head. Set the initial document theme as Main does, based on themeConfig.defaultPreference, to keep the no-JavaScript fallback. Keep Switch in section UI. This feature does not add routing or hydration. Read Astro scripts for browser-script processing and Astro layouts for custom document composition.