PreferenceManager.colorScheme — Eigenschaft · JavaScript-Referenz

Signatur

get PreferenceManager.colorScheme

Beschreibung

Die Eigenschaft colorScheme des PreferenceManager (erreichbar über navigator.preferences) gibt ein PreferenceObject zurück. Dieses Objekt steht für die Nutzereinstellung, die auch die Media-Query prefers-color-scheme steuert. Über das Objekt kann eine Website diese Einstellung für die eigene Seite überschreiben, zum Beispiel mit einem Hell/Dunkel-Umschalter auf der Website.

Der große Vorteil gegenüber selbst gebauten Lösungen mit CSS-Klassen oder localStorage: Nach dem Überschreiben meldet der Browser den neuen Wert auch an @media (prefers-color-scheme: dark), an matchMedia() und an eingebettete Inhalte zurück. Bestehendes CSS muss also nicht umgebaut werden.

Das zurückgegebene PreferenceObject bietet unter anderem:

value – der aktuell wirksame Wert ("light" oder "dark"),
override – der von der Seite gesetzte Überschreibungswert oder null,
validValues – die erlaubten Werte,
requestOverride(value) – fordert eine Überschreibung an und gibt ein Promise zurück,
clearOverride() – entfernt die Überschreibung wieder,
das Ereignis change – wird ausgelöst, wenn sich der wirksame Wert ändert.

Die Eigenschaft ist nur lesbar und hat keine Parameter. Man weist ihr keinen Wert zu, sondern arbeitet mit den Methoden des zurückgegebenen Objekts.

Rückgabewert

Typ

PreferenceObject

Beschreibung

Ein PreferenceObject für die Farbschema-Einstellung mit den Eigenschaften value, override und validValues, den Methoden requestOverride() und clearOverride() sowie dem Ereignis change.

Beispiele

Unterstützung prüfen und aktuellen Wert auslesen

if ('preferences' in navigator && navigator.preferences.colorScheme) {
  const scheme = navigator.preferences.colorScheme;
  console.log('Wirksam:', scheme.value);
  console.log('Überschrieben:', scheme.override);
  console.log('Erlaubt:', scheme.validValues);
} else {
  console.log('Web Preferences API nicht verfügbar');
}

Wirksam: light Überschrieben: null Erlaubt: ['light', 'dark']

Hell/Dunkel-Umschalter mit Rücksetz-Knopf

const scheme = navigator.preferences?.colorScheme;
const toggleBtn = document.querySelector('#theme-toggle');
const resetBtn = document.querySelector('#theme-reset');

toggleBtn.addEventListener('click', async () => {
  if (!scheme) return;
  const next = scheme.value === 'dark' ? 'light' : 'dark';
  try {
    await scheme.requestOverride(next);
    console.log('Farbschema jetzt:', scheme.value);
  } catch (err) {
    console.error('Überschreiben fehlgeschlagen:', err);
  }
});

resetBtn.addEventListener('click', () => {
  // Zurück zur Systemeinstellung
  scheme?.clearOverride();
});

Farbschema jetzt: dark

Auf Änderungen reagieren

const scheme = navigator.preferences?.colorScheme;

const onSchemeChange = () => {
  document.querySelector('#theme-label').textContent =
    scheme.value === 'dark' ? 'Dunkles Design' : 'Helles Design';
};

scheme?.addEventListener('change', onSchemeChange);

// Alternativ über die on-Property:
// scheme.onchange = onSchemeChange;

// CSS-Media-Queries sehen den überschriebenen Wert ebenfalls:
console.log(matchMedia('(prefers-color-scheme: dark)').matches);

true

// Wichtig · Fallstricke

Experimentell: Die Web Preferences API ist ein WICG-Entwurf und derzeit nur in Chromium-Browsern hinter einem Flag verfügbar. Firefox und Safari unterstützen sie nicht. Prüfe die Unterstützung immer vorher (navigator.preferences?.colorScheme) und halte eine Ausweichlösung bereit, etwa CSS-Klassen plus localStorage.
Die Eigenschaft ist nur lesbar: Eine Zuweisung wie navigator.preferences.colorScheme = 'dark' hat keine Wirkung. Nutze stattdessen requestOverride().
requestOverride() mit einem Wert, der nicht in validValues steht, führt zu einem abgelehnten Promise. Fange Fehler deshalb ab.
Die Überschreibung gilt nur für den eigenen Ursprung (Origin). Die Systemeinstellung des Nutzers ändert sich dadurch nicht.
Die API ändert nur, was prefers-color-scheme meldet. Das CSS der Seite muss diese Media-Query oder color-scheme weiterhin selbst auswerten.
Die Details der Spezifikation können sich noch ändern, zum Beispiel ob clearOverride() ein Promise zurückgibt.

Siehe auch

Navigator.preferences PerformanceTiming.connectEnd PreferenceManager.contrast PreferenceManager.reducedData PreferenceManager.reducedMotion