PreferenceObject.override — Methode · JavaScript-Referenz

Signatur

PreferenceObject.override

Beschreibung

Die Eigenschaft override gehört zur Web Preferences API. Über navigator.preferences erreicht man für jede unterstützte Präferenz ein PreferenceObject, zum Beispiel colorScheme, contrast, reducedMotion, reducedTransparency oder reducedData. override gibt an, ob die Website für diese Präferenz einen eigenen Wert gesetzt hat, der vom Wert des Betriebssystems oder Browsers abweicht.

Gesetzt wird ein Override mit requestOverride(value), entfernt wird es mit clearOverride(). Solange ein Override aktiv ist, richten sich die passenden CSS-Media-Queries danach, etwa prefers-color-scheme, sowie die zugehörigen Client Hints. Die Seite kann dann einen „Dunkel/Hell“-Schalter anbieten, ohne dass für das Theme eigene CSS-Klassen nötig sind.

Ist ein Override aktiv, liefert override einen der Werte aus validValues, zum Beispiel "dark" oder "light" bei colorScheme. Ist keines aktiv, ist der Wert null. Das ist wichtig für die Oberfläche: Bei null folgt die Seite der Systemeinstellung, und der Schalter sollte „System“ anzeigen.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuell gesetzte Override-Wert, zum Beispiel "dark", "more" oder "reduce", oder null, wenn kein Override aktiv ist.

Beispiele

Aktuelles Farbschema-Override auslesen

if ('preferences' in navigator) {
  const { override } = navigator.preferences.colorScheme;
  console.log(override ?? 'kein Override – Systemeinstellung aktiv');
} else {
  console.log('Web Preferences API nicht unterstützt');
}

kein Override – Systemeinstellung aktiv

Theme-Umschalter mit drei Zuständen (Hell/Dunkel/System)

const select = document.querySelector('#theme');
const pref = navigator.preferences?.colorScheme;

if (pref) {
  // Anfangszustand: null bedeutet „System“
  select.value = pref.override ?? 'system';

  select.addEventListener('change', async () => {
    try {
      if (select.value === 'system') {
        pref.clearOverride();
      } else {
        await pref.requestOverride(select.value); // 'light' | 'dark'
      }
      console.log('Override jetzt:', pref.override);
    } catch (err) {
      console.error('Override fehlgeschlagen:', err);
    }
  });
}

Override jetzt: dark

Auf Änderungen reagieren (change-Event)

const motion = navigator.preferences?.reducedMotion;

const handleChange = () => {
  console.log('reducedMotion-Override:', motion.override);
};

if (motion) {
  motion.addEventListener('change', handleChange);
  // Alternativ: motion.onchange = handleChange;
  await motion.requestOverride('reduce');
}

reducedMotion-Override: reduce

// Wichtig · Fallstricke

Experimentell: Die API wird bisher nur von Chromium-basierten Browsern unterstützt, dort teils nur hinter einem Flag oder in einem Origin Trial. Vor der Nutzung sollte man deshalb immer mit 'preferences' in navigator oder optionaler Verkettung (?.) prüfen, ob sie vorhanden ist.
override ist schreibgeschützt. Eine Zuweisung wie pref.override = 'dark' hat keine Wirkung (im Strict Mode gibt es einen TypeError). Zum Setzen dient requestOverride().
override zeigt nicht den tatsächlich wirksamen Wert der Präferenz. Ist es null, gilt die Systemeinstellung. Diese fragt man weiterhin mit matchMedia('(prefers-color-scheme: dark)') ab.
Gültige Werte liefert validValues. Wird requestOverride() mit einem ungültigen Wert aufgerufen, wird das Promise abgelehnt.
Overrides gelten pro Herkunft (Origin) und bleiben möglicherweise zwischen Sitzungen erhalten. Beim Laden der Seite sollte man den Wert daher immer neu auslesen.

Siehe auch

Navigator.preferences PreferenceObject.clearOverride() PreferenceObject.requestOverride() URL.createObjectURL() URL.revokeObjectURL()