<!-- Generated by scripts/gen-docs.mts from the JSDoc in registry/. Do not edit; run `pnpm run docs`. -->

# ThemePicker

The look chooser: a row of dots, one per preset, painted with the preset's page and primary colour, with the chosen look's name and mood under them. A press switches the whole app at once, as `data-theme` on `<html>`, and keeps the choice in `localStorage`; `themePresetScript()` inline in `<head>` applies it before first paint. A preset is CSS that keys on `[data-theme="<name>"]`.

## Install

Once per app, with Tailwind CSS v4 and an `@/*` path alias (skip `init` in an existing shadcn app), then the component:

```sh
npx shadcn@latest init --base base --preset nova --yes --no-monorepo
npx shadcn@latest add ourostack/ouro-ui/ouro-base#v1.3.344
npx shadcn@latest add ourostack/ouro-ui/theme-picker#v1.3.344
```

More: [Installing](https://ui.ouroboros.bot/docs/installing.md).

```tsx
import { ThemePicker } from "@/components/ouro/theme-picker/theme-picker";
```

## Example

```tsx
<ThemePicker presets={[{ name: "pearl", label: "Pearl", mood: "Clean white and one clear blue" }, { name: "abyss", label: "Abyss" }]} />
```

## Use instead when

- Use `ColorSchemeToggle` instead for light and dark, which are not looks, and `useThemePreset` for a chooser of your own.

## Props

Type: `ThemePickerProps`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Layout only: margins, grid placement (`ms-auto`). Appearance classes warn in development. |
| `defaultPreset` | `string` |  | The look before a person chooses one; the first of `presets` unless set. |
| `describe` | `boolean` | `true` | Shows the chosen look's name and mood under the dots. |
| `label` | `string` | `"Theme"` | Names the group for screen readers. |
| `presets` (required) | `readonly ThemePreset[]` |  | The looks to choose from, in order; the first is the default unless `defaultPreset` says otherwise. |
| `ref` | `Ref<HTMLDivElement>` |  | Reaches the root. |
| `storageKey` | `string` | `"ouro-theme-preset"` | The `localStorage` key that keeps the choice. |

## `className` is for layout only

Pass margins, width and grid placement (`mt-4`, `w-full`, `col-span-2`).

Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (`hover:`, `sm:`) and any `!` are removed, it starts with `bg-`, `text-`, `border-`, `rounded-`, `shadow-`, `font-`, `ring-`, `from-`, `via-`, `to-`, `fill-` or `stroke-`, or is `border`, `rounded`, `shadow` or `ring`, or has a `dark:` variant. Text wrapping, overflow and table layout classes (`text-wrap`, `text-ellipsis`, `border-collapse`) are layout and do not warn.

Alignment classes (`text-center`) warn too: set alignment on a parent element.

## Types

### `ThemePreset`

One look an app ships, for `ThemePicker`.

```ts
interface ThemePreset {
  /** The value of `data-theme` the preset's CSS keys on: `[data-theme="abyss"]`. */
  name: string;
  /** What a person reads and a screen reader announces: "Abyss". */
  label: string;
  /** One line on the look, shown beside the dots while it is chosen. */
  mood?: string | undefined;
}
```
