# ColorModeToggle

Switch between light, dark, and optional system color modes. Built on `SegmentedControl`. Inside `DesignSystemProvider` it reads context; otherwise pass both `colorMode` and `onColorModeChange`.

## Examples

### Default

Icon-only segments for light and dark. Controlled demos pass `colorMode` / `onColorModeChange`.

```tsx
import { ColorModeToggle } from '@var-ui/react';

<ColorModeToggle colorMode={mode} onColorModeChange={setMode} />
```

```astro
<!-- No Astro binding yet — use @var-ui/react -->
```

```html
<!-- No HTML demo yet — use @var-ui/react -->
```

### Appearance

Set `appearance` to `labels` or `iconsAndLabels`, and `includeSystem` to add a System segment.

```tsx
import { ColorModeToggle, VStack } from '@var-ui/react';
import { useState } from 'react';
import type { ColorMode } from '@var-ui/react';

const [mode, setMode] = useState<ColorMode>('light');

<VStack gap="lg">
  <ColorModeToggle
    appearance="labels"
    includeSystem
    colorMode={mode}
    onColorModeChange={setMode}
  />
  <ColorModeToggle
    appearance="iconsAndLabels"
    includeSystem
    colorMode={mode}
    onColorModeChange={setMode}
  />
</VStack>
```

```astro
<!-- No Astro binding yet — use @var-ui/react -->
```

```html
<!-- No HTML demo yet — use @var-ui/react -->
```

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| appearance | ColorModeToggleAppearance \| undefined | no | 'icons' | How each segment is labeled. |
| aria-label | string \| undefined | no | 'Color mode' | Accessible name for the control group. |
| className | string \| undefined | no |  |  |
| colorMode | ColorMode \| undefined | no |  | Controlled color mode. Pair with `onColorModeChange` to opt out of context. |
| includeSystem | boolean \| undefined | no | false | When true, includes a System segment alongside Light and Dark. |
| onColorModeChange | ((colorMode: ColorMode) => void) \| undefined | no |  | Controlled change handler. Pair with `colorMode` to opt out of context. |
| resolvedColorMode | ResolvedColorMode \| undefined | no |  | Controlled resolved mode (light/dark). Used when `includeSystem` is false and the preference is `'system'`. Defaults to media-query resolution when omitted. |
| size | ControlSize \| undefined | no |  |  |

## Accessibility

Defaults to `aria-label="Color mode"` on the group. Icon-only appearance adds per-segment `aria-label`s (“Light”, “Dark”, “System”). Prefer `labels` or `iconsAndLabels` when the control is not accompanied by nearby explanatory text.