# forced_colors

> Whether a forced colour mode is on, such as a Windows contrast theme, from the forced-colors media query: active or none.

Source: https://whiskerjs.com/signals/forced-colors/ (last updated 2026-10-26)

**forced_colors at a glance (from the library code, signalsVersion 9)**

| Field | Value |
| --- | --- |
| Component name | `forced_colors` |
| In the visitorId | yes |
| structuredId group | [prefs (display and accessibility preferences)](https://whiskerjs.com/docs/identifiers/#structuredid) |
| Hashing | plain value; a digest only when longer than 128 characters or not printable ASCII |
| Excluded under | no browser class |
| Inner timeout | 1000 ms |
| Added in | [signalsVersion 1](https://whiskerjs.com/whats-new/) |

> **In plain words:**
>
> Some people use a mode where the system replaces every website’s colours with a small set of their own, usually with strong contrast. Windows calls these contrast themes. Browsers tell pages whether such a mode is active. WhiskerJS records `active` or `none`.

## What it reads

The CSS `forced-colors` media feature through `window.matchMedia()`.

## How the technique works

| Order | Query | Value reported |
| --- | --- | --- |
| 1 | `(forced-colors: active)` | `active` |
| 2 | `(forced-colors: none)` | `none` |

The first match is reported; neither matching gives `unavailable` with `no_match`.

## Why it helps

Almost everyone reports `none`, so the value tells most devices nothing. For the users who rely on forced colours it is a long-lasting setting, which makes it stable and distinctive for them.

On your server, read it together with the other four preference components. They share the `prefs` part of the [structuredId](https://whiskerjs.com/glossary/#structured-id), so a result where only that part moved usually means a display or accessibility setting changed, not a different device. See [Comparing two results](https://whiskerjs.com/docs/identifiers/#comparing-two-results).

## Stability

Very stable: people who need forced colours keep them on, and people who do not never switch them on. It changes only when the setting changes.

## Browser support and what blocks it

Current Chromium browsers ([Chrome](https://whiskerjs.com/browsers/chrome-desktop/), [Edge](https://whiskerjs.com/browsers/edge/)) and [Firefox](https://whiskerjs.com/browsers/firefox/) understand `forced-colors`; [Safari](https://whiskerjs.com/browsers/safari-macos/) versions that know the feature answer it too, otherwise the result is `no_match`. Forced colour modes are mostly a desktop Windows feature. No browser class excludes it.

## Privacy

This is an accessibility setting. `active` can hint that a user has visual needs, which in some laws can come close to sensitive information. WhiskerJS reads it only to tell devices apart, never shows it anywhere and never decides anything. If you do not need it, leave it out with `collect({ exclude: ['forced_colors'] })` (that changes ids, since it is in the visitorId). See [Privacy](https://whiskerjs.com/docs/privacy/#data-minimisation).

## How WhiskerJS handles noise and failures

| Status | ruleId | When |
| --- | --- | --- |
| `ok` |   | `active` or `none` |
| `unavailable` | `no_api` | no `matchMedia` |
| `unavailable` | `no_match` | neither query matched |
| `blocked` | `threw`, `security_error` | `matchMedia` throws |
| `excluded` | `caller_excluded` | you excluded it |
| `timed_out` | `timeout`, `aborted` | budget or abort |

## Example value

All three headless test browsers in the container reported `none`.

## Questions and answers

### What turns forced_colors to active?

An operating system or browser mode that replaces page colours with a limited palette chosen by the user, best known as the contrast themes on Windows.

### Is this an accessibility setting?

Yes. Users who need high contrast turn it on, so active can say something about a user's needs. Mention it in your privacy notice and use it only for its purpose.

## Related pages

- [prefers_contrast](https://whiskerjs.com/signals/prefers-contrast/): The user's contrast preference.
- [reduced_motion](https://whiskerjs.com/signals/reduced-motion/): Another accessibility setting.
- [What a privacy notice should say](https://whiskerjs.com/privacy/privacy-notice/): How to describe device signals to users.