JavaScript Navigator preferences Property

What You’ll Learn

navigator.preferences returns a PreferenceManager for the current document. Learn MDN’s colorScheme.value check, related preference objects, secure-context notes, matchMedia fallbacks, five examples, and try-it labs.

Introduction

Users set system preferences for dark mode, reduced motion, contrast, and more. CSS already exposes many of these via prefers-* media queries. The experimental User Preferences API adds a JavaScript entry point on navigator.preferences.

Reading navigator.preferences gives you a PreferenceManager. From there you can inspect preference objects such as colorScheme (for example .value === "dark" or "light").

Understanding the preferences Property

navigator.preferences is not a Boolean. It is a manager object for user preference media settings. MDN lists PreferenceManager accessors such as:

• colorScheme — dark / light style preference.
• contrast — contrast preference.
• reducedMotion — reduced motion preference.
• reducedTransparency — reduced transparency preference.
• reducedData — reduced data preference.
• Experimental — feature-detect; do not require it for core UX.

📝 Syntax

General form of the property:

navigator.preferences

Value

• A PreferenceManager object for the current document.

Common patterns

// Always feature-detect first
if (navigator.preferences) {
  // MDN color scheme check:
  if (navigator.preferences.colorScheme.value === "dark") {
    console.log("dark");
  } else {
    console.log("light");
  }
} else {
  // Widely available fallback:
  const dark = window.matchMedia("(prefers-color-scheme: dark)").matches;
  console.log(dark ? "dark (via matchMedia)" : "light (via matchMedia)");
}

Examples Gallery

Examples follow MDN navigator.preferences patterns with safe detection. Prefer Try It Yourself. Many browsers still report the API as missing.

const supported = "preferences" in navigator && !!navigator.preferences;
console.log(supported ? "preferences available" : "preferences missing");

preferences missing
(or "available" in a supporting experimental browser)

function describeColorScheme() {
  if (!navigator.preferences || !navigator.preferences.colorScheme) {
    return "preferences.colorScheme not available";
  }
  if (navigator.preferences.colorScheme.value === "dark") {
    return "dark";
  }
  return "light";
}

console.log(describeColorScheme());

preferences.colorScheme not available
(or "dark" / "light" when supported)

const lines = [];
lines.push("isSecureContext: " + window.isSecureContext);
lines.push(
  "preferences: " +
    ("preferences" in navigator && navigator.preferences ? "present" : "absent")
);
console.log(lines.join("\n"));

isSecureContext: true
preferences: absent
(exact lines depend on browser / page URL)

function preferredScheme() {
  if (navigator.preferences && navigator.preferences.colorScheme) {
    return {
      source: "navigator.preferences",
      value: navigator.preferences.colorScheme.value
    };
  }
  const dark = window.matchMedia("(prefers-color-scheme: dark)").matches;
  return {
    source: "matchMedia",
    value: dark ? "dark" : "light"
  };
}

console.log(JSON.stringify(preferredScheme()));

{"source":"matchMedia","value":"light"}
(or dark / navigator.preferences when available)

function preferencesSnapshot() {
  if (!navigator.preferences) {
    return { ok: false, reason: "api-missing" };
  }
  const keys = [
    "colorScheme",
    "contrast",
    "reducedMotion",
    "reducedTransparency",
    "reducedData"
  ];
  const values = {};
  for (const key of keys) {
    try {
      const obj = navigator.preferences[key];
      values[key] = obj && "value" in obj ? obj.value : null;
    } catch (err) {
      values[key] = null;
    }
  }
  return { ok: true, values };
}

console.log(JSON.stringify(preferencesSnapshot(), null, 2));

{
  "ok": false,
  "reason": "api-missing"
}
(or an object of preference values when supported)

🚀 Common Use Cases

• Theme experiments — read colorScheme.value when the API exists.
• Site-level overrides — explore requestOverride() where supported (still experimental).
• Accessibility labs — inspect reduced motion / contrast preferences in supporting browsers.
• Diagnostics — log a preference snapshot in debug panels.
• Not a CSS replacement — keep prefers-* media queries as the default path.

📝 Notes

• Experimental on MDN — not Baseline.
• Not labeled Deprecated or Non-standard on the property page; still treat as unstable.
• Read-only entry point returning PreferenceManager.
• Related features may require a secure context (HTTPS / localhost).
• Prefer CSS prefers-* and matchMedia for production defaults.
• Related: platform, permissions, Window, JavaScript hub.

💡 Best Practices