---
title: Theme Switcher
description: "Astro controls for previewing color palettes and component appearances."
seo:
    title: "Theme Switcher for Astro — examples and usage"
---

The Theme Switcher stores preview selections in the browser and sends a
`gnostic:preview-change` event. It does not apply theme CSS to the page.
Use an adapter to apply the selection to your previews.

## Installation

```sh
bunx --bun shadcn@latest add @gnosticai/theme-switcher
```

## Usage

```astro
---
import { ThemeSwitcher } from "@/components/ui/theme-switcher"
---

<ThemeSwitcher presets={[{ name: "earth", label: "Earth" }]} />
```

The default styles are Default, Glow, and Soft. Pass an
`appearances` array to use another set. Each option has a `name` and `label`.
Use `layout="stacked"` in a side panel to place the controls in one column.
Older saved selections use the current names. Invalid values use defaults.
Storage is optional: the controls still work if the browser blocks it.

## Blume adapter

This workspace uses `@gnosticai/integrations/blume` to apply selections to
Blume example frames. The adapter is a private workspace package. It is not
required to install this component or to generate a site.

Open **Design** in the docs header to change the preview style and palette.

Use the site's light/dark toggle to change the docs, code blocks, and previews
together. The Theme Switcher does not store a separate color mode.

## When to use Theme Switcher

Use ThemeSwitcher when a site needs explicit choices for palette or appearance. Supply the available options from the theme setup used by the page. Keep the control labels distinct from the light/dark mode control.

## Keyboard and behavior

Test keyboard use and the selected option after navigation. A preview selection does not rewrite the project’s source CSS; export or apply the selected theme through the documented theme workflow.

## Theme and layout

Palette changes affect color tokens, while appearance choices can also affect component details. Check forms and overlays after either change, since a theme must work beyond the preview card.

## Related choices

Use [Theme Toggle](/components/theme-toggle) for only light/dark mode and browse [Themes](/themes) to compare the available presets.