Skip to content

Document the user preferences API#43276

Open
remcohaszing wants to merge 7 commits intomdn:mainfrom
remcohaszing:navigator-preferences
Open

Document the user preferences API#43276
remcohaszing wants to merge 7 commits intomdn:mainfrom
remcohaszing:navigator-preferences

Conversation

@remcohaszing
Copy link
Contributor

Description

This adds content for the navigator.preferences property and related objects.

Motivation

I want to raise more awareness for this awesome upcoming feature.

Additional details

Related issues and pull requests

Relates to mdn/browser-compat-data#29142

@remcohaszing remcohaszing requested review from a team as code owners February 27, 2026 10:25
@remcohaszing remcohaszing requested review from chrisdavidmills and pepelsbey and removed request for a team February 27, 2026 10:25
@github-actions github-actions bot added the Content:WebAPI Web API docs label Feb 27, 2026
@github-actions github-actions bot added the size/l [PR only] 501-1000 LoC changed label Feb 27, 2026
@remcohaszing
Copy link
Contributor Author

The side navigation for the User Preferences API is missing. I couldn’t figure out what’s needed to make it work.

@github-actions
Copy link
Contributor

github-actions bot commented Feb 27, 2026

Preview URLs (16 pages)
Flaws (7)

Note! 12 documents with no flaws that don't need to be listed. 🎉

Found an unexpected or unresolvable flaw? Please report it here.

URL: /en-US/docs/Web/API/Navigator
Title: Navigator
Flaw count: 1

  • macros:
    • Macro domxref produces link /en-US/docs/Web/API/Navigator/standalone which doesn't resolve

URL: /en-US/docs/Web/API/PreferenceObject
Title: PreferenceObject
Flaw count: 2

  • unknown:
    • must be provided
    • must be provided

URL: /en-US/docs/Web/API/PreferenceObject/clearOverride
Title: PreferenceObject: clearOverride() method
Flaw count: 2

  • unknown:
    • must be provided
    • must be provided

URL: /en-US/docs/Web/API/PreferenceObject/requestOverride
Title: PreferenceObject: requestOverride() method
Flaw count: 2

  • unknown:
    • must be provided
    • must be provided

(comment last updated: 2026-03-09 14:03:40)

@hamishwillee
Copy link
Collaborator

The side navigation for the User Preferences API is missing. I couldn’t figure out what’s needed to make it work.

Thanks @remcohaszing - FLy by comment (meaning I am not giving this a proper review, at least at this time)

Sidebar content for Web API configured in https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json - the name of the API is used in a macro at the top of the Web API docs - do a search in docs on any of the other names here to see how it works.

FWIW often I wait for the BCD to be accepted before reviewing docs.

Copy link
Contributor

@chrisdavidmills chrisdavidmills left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi there @remcohaszing, and thank you for this contribution. This is a really good piece of work. I've made quite a few comments, but they are mainly just similar requests on each page, for the same stuff that is missing.

Let me know if you need any help or have questions.

#### JavaScript

```js
for (const input of document.getElementsByName("color-scheme")) {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if this code is quite right. I did a bit of testing, and it was giving me a syntax error, so I rewrote it to this:

for (input of document.getElementsByName("color-scheme")) {
  input.addEventListener("change", () => {
    if (input.value === "system") {
      navigator.preferences.colorScheme.clearOverride();
    } else {
      navigator.preferences.colorScheme.requestOverride(input.value);
    }
    
    console.log(navigator.preferences.colorScheme.override);
  });
}

When I run this, the override value is always logged as "dark", whichever radio I push.

Also, wouldn't it be nice to extend the example a bit to provide some minimal styles in a media query that sets a light and dark color scheme on the page when the radios are chosen?

Making it into a live example would be cool as well, as the reader can test it live on the page. See our live samples guide for more info (https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Live_samples)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, a live example would be great! I didn’t know how to make one. Thanks for pointing this out. It’s getting late now, so I’ll do this another time.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added a live example. I removed the system option because of w3c/csswg-drafts#13613.

Copy link
Contributor Author

@remcohaszing remcohaszing left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the review! I really appreciate it.

#### JavaScript

```js
for (const input of document.getElementsByName("color-scheme")) {
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, a live example would be great! I didn’t know how to make one. Thanks for pointing this out. It’s getting late now, so I’ll do this another time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Content:WebAPI Web API docs size/l [PR only] 501-1000 LoC changed

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants