JavaScript Navigator preferences Property

Beginner
5 min read
Updated: Nov 2026
3 examples
Property
Decorative image with the word PREFERENCES

Definition

navigator.preferences is a read-only property that returns a PreferenceManager for the current document — the entry point to the experimental User Preferences API (MDN).

Read the notes below before you rely on this property. Prefer feature detection when support is limited.

Syntax

Use navigator.preferences. Start with this line.

JavaScript
navigator.preferences
CallWhat it does
navigator.preferencesPrimary signature.

Built into the browser. Read navigator.preferences on Navigator — no import required.

Library declarations
JavaScript
navigator.preferences

Parameters

ParameterDescription
colorScheme.valueOptional. Dark / light preference string
Other prefsOptional. contrast, reducedMotion, reducedTransparency, reducedData

Return Value

Return ValueDescription
*The current value of navigator.preferences.

JavaScript Examples

Example 1 — Feature-Detect Support

Check whether the experimental property exists before using it.

JavaScript
if ("preferences" in navigator && navigator.preferences) {
  console.log("preferences available");
} else {
  console.log("preferences missing — use matchMedia / CSS");
}
Try It Yourself

How It Works

  1. Use in. Checks whether the property exists on navigator.
  2. Truthiness. Also ensure the returned object is present.
  3. Common path. Most browsers today omit the API → fall back.
  4. Rule. Never call .colorScheme without detecting first.

Example 2 — MDN colorScheme.value

Read dark vs light when the experimental API is available.

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

console.log(readColorScheme());
Try It Yourself

How It Works

  1. Guard. Exit if preferences or colorScheme is missing.
  2. Read .value. MDN compares it to "dark".
  3. Branch. Dark → dark theme path; otherwise treat as light.
  4. Reality check. Expect the “not available” path in most browsers today.

Example 3 — matchMedia Fallback

Use the stable media-query API when preferences is missing.

JavaScript
function prefersDark() {
  if (navigator.preferences && navigator.preferences.colorScheme) {
    return navigator.preferences.colorScheme.value === "dark";
  }
  return window.matchMedia("(prefers-color-scheme: dark)").matches;
}

console.log(prefersDark() ? "dark" : "light");
Try It Yourself

How It Works

  1. Try the new API. Use colorScheme.value when present.
  2. Fall back. matchMedia is widely available and reliable.
  3. Return a boolean. Easy to wire into theme toggles.
  4. Best practice. Ship CSS prefers-color-scheme even when JS runs.
Compatibility

Browser Support

navigator.preferences is marked Experimental on MDN. It is not Baseline. Expect missing support in current mainstream browsers — feature-detect and keep matchMedia / CSS fallbacks.

✓ Experimental · Limited support

Navigator.preferences

Returns a PreferenceManager for the User Preferences API. Use only as an optional enhancement; stable theming should rely on prefers-* media queries.

Limited Experimental
Google Chrome Experimental / limited or unavailable
Limited
Mozilla Firefox Experimental / limited or unavailable
Limited
Apple Safari Experimental / limited or unavailable
Limited
Microsoft Edge Experimental / limited or unavailable
Limited
Opera Not a production dependency
Limited
Internet Explorer Not available
No support
preferences Experimental

Bottom line: Do not ship production theme logic that requires navigator.preferences. Detect it when present; always fall back to matchMedia and CSS.

Frequently Asked Questions

It is a read-only Navigator property that returns a PreferenceManager object — the entry point to the experimental User Preferences API for reading user preference settings such as color scheme.
MDN marks it Experimental. It is not Baseline. Always feature-detect and keep a fallback such as CSS prefers-* media queries or window.matchMedia.
MDN’s pattern: if (navigator.preferences.colorScheme.value === "dark") { /* dark */ } else { /* light */ }. Feature-detect navigator.preferences first.
PreferenceManager can provide PreferenceObject accessors such as colorScheme, contrast, reducedMotion, reducedTransparency, and reducedData — corresponding to prefers-* media queries.
PreferenceManager is documented as a secure-context feature (HTTPS or localhost) in supporting browsers. Prefer testing on HTTPS.
No. The property is read-only. You use the returned PreferenceManager and its PreferenceObject properties (for example colorScheme.value).

Next: presentation

Continue with the next Navigator property in the JavaScript guide.

presentation tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

6 people found this page helpful

JavaScript Navigator platform Property JavaScript Navigator presentation Property