---
id: "packages/active-ui/mode-toggle"
title: "ModeToggle"
description: "One icon button that switches between the light and the dark scheme - the sun in light, the moon in dark, no menu."
url: "/packages/active-ui/mode-toggle"
locale: "en"
revision: "bf421620b2e46f1a"
---

# ModeToggle

`ModeToggle` is the colour-scheme button of an application header: the sun while the light scheme is
shown, the moon while the dark one is, and a click switches to the other. There is no menu and no
"system" choice to pick.

**Example: The colour-scheme button**

Client: Runs entirely in your browser. Source: `examples/ui/mode-toggle.tsx`.

```tsx
// apps/docs/examples/ui/mode-toggle.tsx
'use client';

import {ModeToggle} from '@workspace/active-ui/components/composed/mode-toggle';
import {TooltipProvider} from '@workspace/active-ui/components/primitives/tooltip';

/**
 * The colour-scheme button of an application header, under this site's
 * theme provider: a click switches the whole site between light and dark,
 * like the button in the header above.
 */
export default function ModeToggleExample() {
  return (
    <TooltipProvider>
      <ModeToggle
        label="Colour scheme"
        schemeLabels={{light: 'Light', dark: 'Dark'}}
        showTooltip
      />
    </TooltipProvider>
  );
}
```

## What the composition adds

- **One click, one switch**: it stores the opposite of the scheme in effect through `useTheme()`
  of the [theme provider](/packages/active-ui/theming).
- **A first visit follows the device**: until the reader clicks, the provider keeps the mode the
  host gave it. A host that starts in `system` (no stored choice yet) shows the device's scheme; the
  first click stores light or dark.
- **The right icon before hydration**: the sun and the moon follow the `dark` class on the document,
  so the icon is right as soon as the page paints.
- **A name with the state**: `label` followed by the scheme shown ("Colour scheme: Dark");
  `showTooltip` shows `label` as a tooltip. Put a `TooltipProvider` above it to set the delay.

## Usage

```tsx
import {ModeToggle} from '@workspace/active-ui/components/composed/mode-toggle';

<ModeToggle
  label="Colour scheme"
  schemeLabels={{light: 'Light', dark: 'Dark'}}
  showTooltip
/>;
```

## What your application provides

- A `ThemeProvider` above it, with the persistence of your choice (a cookie your server reads, so a
  reload shows the stored scheme without a flash).
- The texts, translated: `label` and the two names in `schemeLabels`.
- Whether a reader can return to "follow the device": this button never chooses `system`. Offer it
  elsewhere if your product wants it.

## Accessibility and keyboard

A `<button>`, reached with `Tab` and pressed with `Enter` or `Space`. Its accessible name says the
scheme in effect, so a screen reader hears the change after a press.

## API

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | yes | The name of the control, supplied translated: "Colour scheme". Shown as the tooltip and, followed by the scheme in effect, as the accessible name ("Colour scheme: Dark"). |
| `schemeLabels` | `{ light: string; dark: string; }` | yes | The names of the two schemes, supplied translated, said after {@link label} in the accessible name. |
| `className` | `string` | no | Classes for the button. |
| `showTooltip` | `boolean` | no | Also shows {@link label} as a tooltip. Off by default, for the reason `FullScreen` gives: the delay lives on the caller's `Tooltip.Provider`. |

**ModeToggleProps**

```ts
interface ModeToggleProps {
  label: string;
  schemeLabels: {light: string; dark: string};
  showTooltip?: boolean;
  className?: string;
}
```