# Theme setting

The person's control for the theme: "Match my system", "Light", "Dark" or "High contrast", on its own, for an app with no profile page (`ProfileSettings` draws the same control). It stores and applies nothing: the choice goes back through `onValueChange`, and the app keeps it and puts it on the page, as `data-theme="light"`, `"dark"` or `"hc"` on `<html>` (no attribute for "Match my system", which follows the system's setting). Nothing is chosen for the person: without a `value` it shows "Choose a theme".

```
<ThemeSetting value={settings.theme} onValueChange={(theme) => setSettings({ ...settings, theme })} />
```

An app without a high-contrast theme leaves that choice out: `choices={["system", "light", "dark"]}`.

- Registry name: `theme-setting` (`@candor/theme-setting`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/theme-setting

## Install

```bash
npx candor-ui add theme-setting
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/theme-setting`.
It brings in: locale, locked, select, tokens, utils.

## Example

```tsx
"use client"

import * as React from "react"
import { ThemeSetting, type ThemeChoice } from "@/components/candor/theme-setting"

/*
 * The app keeps the choice (here in state; in an app, with the person's settings) and puts it on the page: data-theme
 * on <html>, or no attribute for "Match my system". This example keeps it in a sentence, so the docs page's own theme
 * stays as it is.
 */
export default function Example() {
  const [theme, setTheme] = React.useState<ThemeChoice | undefined>(undefined)
  return (
    <div className="flex max-w-xs flex-col gap-3 text-sm">
      <ThemeSetting value={theme} onValueChange={setTheme} />
      <p className="text-xs text-muted-foreground">
        {theme === undefined ? "Nothing chosen yet." : theme === "system" ? "No data-theme attribute: the page follows the system." : `data-theme="${theme}" on <html>.`}
      </p>
    </div>
  )
}
```

## <ThemeSetting>

Props:

- `value?: ThemeChoice | undefined`: The person's choice as the app last stored it. Left out, nothing is chosen and the control says "Choose a theme".
- `onValueChange: (next: ThemeChoice) => void`: Called with the choice when the person picks one.
- `label?: string | undefined`: The words above the control. Defaults to "Theme".
- `optionLabels?: Partial<Record<ThemeChoice, string>> | undefined`: The options' words, where the app keeps them somewhere other than `themeSetting` (ProfileSettings passes its own).
- `choices?: readonly ThemeChoice[] | undefined`: The choices to offer, for an app that doesn't have all four themes. Defaults to all four. They're listed in the usual order (system, light, dark, high contrast) whatever order they're given in; an empty list offers all four. A `value` that isn't among them shows as nothing chosen ("Choose a theme"), so the person picks one of the choices offered; the app goes on applying what it stored until they do.
- `locked?: string | null | undefined`: Why the theme can't be changed now (the organisation sets it). The control stays focusable and says why.
- `className?: string | undefined`: Classes for the wrapper, merged with Candor's.

## Strings (`themeSetting`)

The fixed words, English by default. Override any of them under `themeSetting` in `<LocaleProvider strings={{ themeSetting: { … } }}>`; the table is exported as `themeSettingStrings`.

- `label`: Theme
- `placeholder`: Choose a theme
- `system`: Match my system
- `light`: Light
- `dark`: Dark
- `hc`: High contrast

## Types

### ThemeChoice

The person's theme: follow the system's light or dark, or always light, dark or high contrast.

```ts
"system" | "light" | "dark" | "hc"
```

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider`: its fixed strings in `strings`, its nouns in `nouns`; entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.