PreferenceObject.requestOverride() — Methode · JavaScript-Referenz

Signatur

PreferenceObject.prototype.requestOverride(value)

Beschreibung

Die Methode requestOverride() gehört zum Interface PreferenceObject der experimentellen User Preferences API. Ein PreferenceObject erreichen Sie über navigator.preferences, etwa navigator.preferences.colorScheme, .contrast, .reducedMotion, .reducedTransparency oder .reducedData. Mit requestOverride() setzt eine Website für eine dieser Präferenzen einen eigenen Wert. Dieser gilt dann für die passenden CSS-Media-Queries (z. B. @media (prefers-color-scheme: dark)) und für matchMedia().

Gedacht ist die Methode für seiteneigene Einstellungen, zum Beispiel einen Umschalter zwischen hellem und dunklem Design. Bisher mussten Entwicklerinnen und Entwickler dafür CSS-Klassen oder eigene Custom Properties parallel zu den Media-Queries pflegen. Mit einem Override reicht ein einziger Satz Media-Queries, und die Seite folgt trotzdem der Wahl im Umschalter. Außerdem gilt der Override für die gesamte Origin und bleibt erhalten. Er wirkt also auch in anderen Tabs und nach einem Neuladen.

Der Aufruf ist asynchron und liefert ein Promise. Ist der Override gesetzt, wird es erfüllt. Ist der Wert ungültig, wird es mit einem Fehler abgelehnt. Welche Werte erlaubt sind, steht in validValues, der aktuell gesetzte Override in override. Mit clearOverride() heben Sie den Override wieder auf. Dann gilt wieder die Einstellung des Betriebssystems bzw. des Browsers.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	string		Der gewünschte Override-Wert. Er muss in `validValues` des jeweiligen `PreferenceObject` stehen, z. B. `"light"` oder `"dark"` bei `colorScheme`, `"reduce"` oder `"no-preference"` bei `reducedMotion`, `"more"`, `"less"` oder `"no-preference"` bei `contrast`.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das ohne Wert erfüllt wird, sobald der Override gesetzt ist. Bei einem ungültigen Wert wird es abgelehnt, typischerweise mit einem TypeError.

Beispiele

Dunkles Design per Umschalter erzwingen

const toggle = document.querySelector('#dark-mode-toggle');

toggle.addEventListener('change', async () => {
  const pref = navigator.preferences?.colorScheme;
  if (!pref) {
    console.warn('User Preferences API nicht verfügbar');
    return;
  }
  try {
    if (toggle.checked) {
      await pref.requestOverride('dark');
    } else {
      await pref.clearOverride();
    }
    console.log('Aktueller Override:', pref.override);
  } catch (err) {
    console.error('Override fehlgeschlagen:', err);
  }
});

Aktueller Override: dark

Wert vorher gegen validValues prüfen

const setMotionPreference = async (value) => {
  const pref = navigator.preferences?.reducedMotion;
  if (!pref) return false;

  if (!pref.validValues.includes(value)) {
    console.warn(`Ungültiger Wert: ${value}. Erlaubt: ${pref.validValues.join(', ')}`);
    return false;
  }
  await pref.requestOverride(value);
  return true;
};

console.log(await setMotionPreference('reduce'));
console.log(matchMedia('(prefers-reduced-motion: reduce)').matches);

true true

Auf Änderungen reagieren (auch aus anderen Tabs)

const pref = navigator.preferences?.contrast;

if (pref) {
  pref.addEventListener('change', () => {
    console.log('Kontrast-Override jetzt:', pref.override ?? '(keiner)');
  });

  await pref.requestOverride('more');
}

Kontrast-Override jetzt: more

Fallback mit Feature-Erkennung

const applyTheme = async (theme) => {
  if ('preferences' in navigator) {
    await navigator.preferences.colorScheme.requestOverride(theme);
  } else {
    // Fallback: Klasse am Wurzelelement setzen
    document.documentElement.dataset.theme = theme;
    localStorage.setItem('theme', theme);
  }
};

await applyTheme('light');

// Wichtig · Fallstricke

Experimentell: Die User Preferences API ist ein Entwurf der WICG und bisher nur in Chromium-Browsern hinter einem Flag bzw. in einem Origin Trial verfügbar. Firefox und Safari unterstützen sie nicht. Prüfen Sie deshalb immer, ob navigator.preferences existiert, und sehen Sie einen Fallback vor, zum Beispiel über CSS-Klassen oder localStorage.
Gültigkeit für die ganze Origin: Der Override bleibt erhalten und gilt für alle Seiten und Tabs derselben Origin. Wenn Sie ihn nicht mehr brauchen, heben Sie ihn mit clearOverride() ausdrücklich auf. Sonst bleibt er über Sitzungen hinweg bestehen.
Ungültige Werte: Werte, die nicht in validValues stehen, führen dazu, dass das Promise abgelehnt wird. Verwenden Sie also await in einem try/catch oder hängen Sie .catch() an.
Barrierefreiheit: Überschreiben Sie Präferenzen wie reducedMotion oder contrast nur auf ausdrücklichen Wunsch der Nutzerinnen und Nutzer. Ein Override gegen die Systemeinstellung kann Menschen schaden, die auf reduzierte Bewegung oder hohen Kontrast angewiesen sind.
Nach dem Entwurf können Browser den Aufruf an eine Nutzeraktion knüpfen oder ablehnen. Rufen Sie die Methode deshalb am besten in einem Event-Handler auf, etwa bei click oder change.
Die API kann sich noch ändern. Prüfen Sie Namen und Verhalten vor dem Einsatz im Produktivbetrieb am aktuellen Entwurf.

Siehe auch

Navigator.preferences PreferenceObject.clearOverride() PreferenceObject.override Bluetooth.requestDevice() Element.requestPointerLock()