Skip to main content

Actions

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>"].

PearlClean white and one clear blue

Install

Hand it to your agent
Add ThemePicker from Ouro UI to this app. Read https://ui.ouroboros.bot/docs/theme-picker.md first and follow it.

Or by hand. Once per app, with Tailwind CSS v4 and an @/* path alias (Ouro HX is built on Base UI, so --base base; skip -t in an existing app):

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

Then the component. From v0.8.0 it installs only the helpers it imports and never touches your stylesheet (Installing):

npx shadcn@latest add ourostack/ouro-ui/theme-picker#v1.3.344

Or, with the @ouro namespace set up:

npx shadcn@latest add @ouro/ouro-base @ouro/theme-picker

Its tests, stories and Playwright spec are optional. They need Vitest 4.1.11 or later, and from v0.8.0 never change a version your app has (Testing):

npx shadcn@latest add ourostack/ouro-ui/theme-picker#v1.3.344 ourostack/ouro-ui/theme-picker-tests#v1.3.344
import { ThemePicker } from "@/components/ouro/theme-picker/theme-picker";

Paths use shadcn's default @/ alias; the CLI rewrites them to yours.

Example

<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.

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

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;
}