Signatur
Beschreibung
navigator.preferences ist der Einstiegspunkt der experimentellen User Preferences API. Die Eigenschaft gibt ein PreferenceManager-Objekt für das aktuelle Dokument zurück. Darüber kommen Sie an die Nutzereinstellungen heran, die Sie sonst nur über CSS-Media-Features wie prefers-color-scheme, prefers-contrast, prefers-reduced-motion, prefers-reduced-transparency oder prefers-reduced-data abfragen könnten.
Jede Einstellung ist ein PreferenceObject (z. B. navigator.preferences.colorScheme). Es bietet:
value: den aktuell wirksamen Wert, also die Systemeinstellung oder die Überschreibung,validValues: die zulässigen Werte,override: die aktive Überschreibung odernull,requestOverride(value): setzt eine Überschreibung für diese Website (gibt ein Promise zurück),clearOverride(): entfernt die Überschreibung,- das Ereignis
change, das bei jeder Änderung des Werts ausgelöst wird.
Der große Vorteil: Überschreibt eine Website eine Einstellung, zum Beispiel über einen eigenen Dunkelmodus-Schalter, wirkt das direkt auf die CSS-Media-Queries. Sie müssen die Stile also nicht doppelt pflegen, etwa über Klassen wie .dark und zusätzlich @media (prefers-color-scheme: dark).
Die Eigenschaft ist schreibgeschützt und hat keine Parameter. Setzen Sie sie nur mit Feature-Erkennung ein und sehen Sie immer einen Rückfall über matchMedia() vor.
Rückgabewert
PreferenceManager mit den PreferenceObject-Eigenschaften colorScheme, contrast, reducedMotion, reducedTransparency und reducedData. In Browsern ohne Unterstützung ist navigator.preferences undefined.Beispiele
Unterstützung prüfen und aktuelle Einstellungen lesen
if ('preferences' in navigator) {
const { colorScheme, reducedMotion } = navigator.preferences;
console.log('Farbschema:', colorScheme.value);
console.log('Erlaubte Werte:', colorScheme.validValues);
console.log('Reduzierte Bewegung:', reducedMotion.value);
} else {
// Rückfall über matchMedia
const dark = matchMedia('(prefers-color-scheme: dark)').matches;
console.log('Farbschema (Rückfall):', dark ? 'dark' : 'light');
}Dunkelmodus-Schalter, der auf CSS-Media-Queries wirkt
const toggle = document.querySelector('#theme-toggle');
toggle.addEventListener('click', async () => {
const pref = navigator.preferences?.colorScheme;
if (!pref) {
document.documentElement.classList.toggle('dark');
return;
}
const next = pref.value === 'dark' ? 'light' : 'dark';
try {
await pref.requestOverride(next);
console.log('Überschrieben auf:', pref.override);
} catch (err) {
console.error('Überschreiben nicht erlaubt:', err);
}
});Auf Änderungen reagieren und Überschreibung zurücksetzen
const motion = navigator.preferences?.reducedMotion;
if (motion) {
const apply = () => {
document.body.dataset.animations =
motion.value === 'reduce' ? 'off' : 'on';
console.log('Animationen:', document.body.dataset.animations);
};
motion.addEventListener('change', apply);
apply();
// Zurück zur Systemeinstellung
document.querySelector('#reset')
?.addEventListener('click', () => motion.clearOverride());
}// Wichtig · Fallstricke
- Experimentell: Die API stammt aus einem WICG-Entwurf und ist bisher nur in Chromium hinter einem Flag verfügbar („Experimental Web Platform features“). Firefox und Safari unterstützen sie nicht. Prüfen Sie deshalb immer mit
'preferences' in navigatorodernavigator.preferences?.. - Überschreibungen gelten nur für den eigenen Origin und ändern nie die Systemeinstellung.
requestOverride()kann abgelehnt werden, zum Beispiel ohne Nutzerinteraktion oder mit einem Wert, der nicht invalidValuessteht. Fangen Sie Fehler des Promise daher ab. - Wie lange eine Überschreibung erhalten bleibt, legt der Browser fest. Verlassen Sie sich nicht darauf, dass sie Sitzungen überdauert, und speichern Sie die Wahl bei Bedarf zusätzlich selbst, etwa in
localStorage. - Die Eigenschaft ist schreibgeschützt. Eine Zuweisung an
navigator.preferenceshat keine Wirkung. - Name und Form der API können sich noch ändern. Verwenden Sie sie in Produktivcode nur als schrittweise Verbesserung.