# `colorMode`

Configure the behavior of the color mode UI control and add more color modes.
The default theme (`@redocly/theme`) includes two color modes: light mode and dark mode.
Color modes can be set to a default value, or with the user's operating system preference.

The **code** colorMode option also supports page-level configuration using front matter.

## Options

| Option | Type | Description |
| --- | --- | --- |
| hide | boolean | Specifies if the color mode selector is hidden. Default: `false`. |
| ignoreDetection | boolean | Specifies if the system color mode detection is ignored. Default: `false`. |
| modes | [string] | List of possible color mode values. Default: ```yaml   - light   - dark ``` |

### Priority

The color mode is selected for a user based on the following priority from top (highest priority) to bottom (lowest priority):

- If a user sets a `mode` it is stored in `localStorage`.
  If the mode is in `localStorage` it's selected.
- If a user visits and `ignoreDetection` is not `true`, the value is detected from the user's operating system (when possible).
- The first mode in the `modes` list applies.

## Examples

### `hide` example

The following example hides the color mode toggle.

```yaml
colorMode:
  hide: true
```

### `ignoreDetection` example

Color mode operating system detection is on by default.
The following example ignores the user's operating system color mode.

```yaml
colorMode:
  ignoreDetection: true
```

### `modes` list example

Specify the list of available `colorMode` options in the `modes` list.
You must add a mode to reference it in the modes list.
Learn how to add a mode by reading the [Add new color modes](/docs/platform/branding/customize-color-modes#add-new-color-modes) section.

```yaml
colorMode:
  ignoreDetection: true
  modes:
    - dark-contrast
    - dark
    - light
```

The first `mode` from the `modes` list applies by default if `ignoreDetection` is `true`.

## Resources

- **[Customize color modes](/docs/platform/branding/customize-color-modes)** - Style light and dark modes with CSS, set a logo for each mode, or add new color modes
- **[Front matter configuration options](/docs/platform/config/front-matter-config)** - Use front matter to show or hide the color mode switcher on individual pages for custom layouts
- **[Configuration options](/docs/platform/config)** - Explore other project configuration options for comprehensive documentation and platform customization