# ThemeSwitcher

> A segmented control that lets people choose light, dark, high contrast or system.

Category: Theming · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/theme-switcher

ThemeSwitcher reads and writes the ThemeProvider preference. Place it where people expect appearance settings: a header, footer or settings page. Limit the options when a product only supports some modes, but always keep high contrast available where possible.

## Import

```tsx
import { ThemeSwitcher } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Icons

```tsx
import { ThemeSwitcher } from '@bindshq/stance-react';

export function Basic() {
  return <ThemeSwitcher />;
}
```

### With labels

Visible labels suit settings pages.

```tsx
import { ThemeSwitcher } from '@bindshq/stance-react';

export function WithLabels() {
  return <ThemeSwitcher showLabels />;
}
```

### Compact

The small size fits dense headers and footers.

```tsx
import { ThemeSwitcher } from '@bindshq/stance-react';

export function Small() {
  return <ThemeSwitcher size="sm" />;
}
```

### Limited options

```tsx
import { ThemeSwitcher } from '@bindshq/stance-react';

export function LimitedOptions() {
  return <ThemeSwitcher showLabels options={['light', 'dark', 'system']} label="Appearance" />;
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| ThemeSwitcher | `showLabels` | `boolean` | `false` | Show text beside each icon. Icons alone get accessible names and titles. |
| ThemeSwitcher | `options` | `Array<'light' \| 'dark' \| 'high-contrast' \| 'system'>` | `all four` | Which choices to offer. |
| ThemeSwitcher | `label` | `string` | `'Theme'` | Accessible name of the radio group. |
| ThemeSwitcher | `size` | `'sm' \| 'md'` | `'md'` | Control size. |

## Accessibility

- A radiogroup of radio buttons with aria-checked; the group is named “Theme” by default.
- One tab stop: arrow keys move between options and select them, matching native radio groups.
- Icon-only options have accessible names and visible tooltips through title.

## Keyboard

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus into and out of the group. |
| `←` `→` | Selects the previous or next theme. |
| `Home` `End` | Moves to the first or last option. |

## Guidelines

**Do**

- Offer System so the product follows operating-system changes.
- Keep the switcher in the same place on every page.

**Don’t**

- Hide high contrast behind a separate setting.
- Use a switch for three or more options.

## Related

- https://stanceui.com/components/theme-provider
- https://stanceui.com/components/toggle-button