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

# ColorSchemeToggle

The control that switches the app between light, dark and the system's scheme, and keeps the choice. `variant="menu"`, the default, is an icon button for a header: the sun or the moon of the scheme the page shows, opening a menu of Light, Dark and System, the current one checked. `variant="segmented"` shows the three side by side, for a settings page. Either way the choice applies at once, as the `.dark` class on `<html>` that shadcn themes switch on, and is kept in `localStorage`.

```tsx
import { ColorSchemeToggle } from "@/components/ouro/color-scheme-toggle/color-scheme-toggle";
```

## Example

```tsx
<Navbar label="Main" items={items} actions={<ColorSchemeToggle />} />
<ColorSchemeToggle variant="segmented" label="Appearance" />
```

## Usage

It works on its own, but the choice then shows only once the toggle changes it: wrap the app in `ColorSchemeProvider`, which applies the kept choice on every page and follows the system's setting live, and put `colorSchemeScript()` in `<head>` so a reload never flashes the wrong scheme. For a control of your own, `useColorScheme()` gives the scheme and its setter.

## Use instead when

- Use `Switch` with `useColorScheme()` instead for a plain dark-mode on/off, and `SegmentedControl` for other choices of how a view looks.

## Props

Type: `ColorSchemeToggleProps`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Layout only: margins, grid placement (`ms-auto`). Appearance classes warn in development. |
| `label` | `string` | `"Color scheme"` | Names the control for screen readers: the button's name, or the segmented control's label. |
| `labels` | `ColorSchemeLabels` |  | The words for each scheme. |
| `ref` | `Ref<HTMLElement>` |  | Reaches the menu button, or the segmented control's group. |
| `variant` | `"menu" \| "segmented"` | `"menu"` | `menu` is an icon button, the sun or the moon of the scheme the page shows, that opens a menu of Light, Dark and System, for a header. `segmented` shows the three side by side, for a settings page. |

## Don't use

These are not props. Passing one fails the type check with the fix in the error, and in development a console message names the fix.

- `onChange`: Not a prop. The toggle applies the choice itself; to react to it, read `useColorScheme().resolved`.
- `theme`: Not a prop. Ouro UI says color scheme: `<ColorSchemeToggle />` with `ColorSchemeProvider` around the app.
- `value`: Not a prop. The toggle keeps the scheme itself, through `ColorSchemeProvider`; read it with `useColorScheme()`.

## `className` is for layout only

Pass margins, width and grid placement (`mt-4`, `w-full`, `col-span-2`). Your classes always win over Ouro UI's: ColorSchemeToggle merges `className` last with `cn` (tailwind-merge), so a class that conflicts with its own replaces it.[^layout-classes]

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

### `ColorSchemeLabels`

The words for each scheme, for apps in other languages.

```ts
interface ColorSchemeLabels {
  /** @default "Light" */
  light?: string | undefined;
  /** @default "Dark" */
  dark?: string | undefined;
  /** @default "System" */
  system?: string | undefined;
}
```

[^layout-classes]: test:registry/ouro/components/ouro/color-scheme-toggle/color-scheme-toggle.test.tsx::ColorSchemeToggle > forwards a ref to the button or the group, and lets app layout classes win verify:testExists(registry/ouro/components/ouro/color-scheme-toggle/color-scheme-toggle.test.tsx::ColorSchemeToggle > forwards a ref to the button or the group, and lets app layout classes win)