极速阅览

User Preferences API - Web APIs | MDN

Toggle sidebar

Theme

OS default
Light
Dark

English (US)

Remember language Learn more

Concepts and Usage

Supporting user agents define values for the CSS media queries prefers-color-scheme, prefers-contrast, prefers-reduced-motion, prefers-reduced-transparency, and prefers-reduced-data. The PreferenceManager object provides programmatic access to these preferences, allowing page authors to listen for preference changes and override them.

Examples

Dark Mode Toggle

The following code implements a minimal dark mode toggle.

HTML

The HTML features a form containing three radio buttons. These radio buttons set the color-scheme field to either system, light, or dark.

html
<!doctype html>
<html lang="en-US">
  <head>
    <meta name="color-scheme" content="light dark" />
  </head>
  <body>
    <form>
      <label>
        <input type="radio" name="color-scheme" value="light" />
        Light
      </label>
      <label>
        <input type="radio" name="color-scheme" value="dark" />
        Dark
      </label>
    </form>
  </body>
</html>

JavaScript

The JavaScript registers change event listeners for all elements named color-scheme. If the value is system, the handler clears the color scheme override. Otherwise, it requests a color scheme override with the value of the input element.

js
if (navigator.preferences) {
  const inputs = {
    light: document.querySelector('[name="color-scheme"][value="light"]'),
    dark: document.querySelector('[name="color-scheme"][value="dark"]'),
  };

  inputs[navigator.preferences.colorScheme.value].checked = true;

  inputs.light.addEventListener("change", () => {
    navigator.preferences.colorScheme.requestOverride("light");
  });
  inputs.dark.addEventListener("change", () => {
    navigator.preferences.colorScheme.requestOverride("dark");
  });

  navigator.preferences.colorScheme.addEventListener("change", () => {
    inputs[navigator.preferences.colorScheme.value].checked = true;
  });
} else {
  document.body.append(
    "Your browser doesn’t support the navigator.preferences API",
  );
}

Result

body {
  font-family: system-ui, sans-serif;
}

label {
  display: block;
  margin: 0.5em 0;
}

Specifications

Specification

Media Queries Level 5
# preferences-attribute

Browser compatibility

api.Navigator.preferences

Enable JavaScript to view this browser compatibility table.

api.PreferenceManager

Enable JavaScript to view this browser compatibility table.

api.PreferenceObject

Enable JavaScript to view this browser compatibility table.

Help improve MDN

Was this page helpful to you?

Yes No

Learn how to contribute

This page was last modified on Mar 23, 2026 by MDN contributors.

View this page on GitHub • Report a problem with this content

User Preferences API
Interfaces
1. PreferenceManager
2. PreferenceObject
Properties
1. Navigator.preferences

User Preferences API

In this article

HTML

JavaScript

Result

Help improve MDN