Signatur
Beschreibung
Die Eigenschaft media des Interfaces HTMLMetaElement spiegelt das HTML-Attribut media eines <meta>-Elements. Ihr Wert ist ein String mit einer Media Query, zum Beispiel (prefers-color-scheme: dark) oder screen and (max-width: 600px).
In der Praxis ist sie nur zusammen mit name="theme-color" relevant. Damit legt man fest, unter welchen Bedingungen eine bestimmte Theme-Farbe für die Browser-Oberfläche (Adressleiste, Titelleiste von PWAs, Tab-Leiste) gilt. Typisch sind zwei <meta name="theme-color">-Tags: eines für den hellen und eines für den dunklen Modus.
Über JavaScript kann man die Media Query zur Laufzeit auslesen oder ändern, etwa wenn die Nutzerin in der Anwendung selbst zwischen hellem und dunklem Design umschaltet. Wenn das Attribut fehlt, liefert die Eigenschaft einen leeren String. Das Meta-Tag gilt dann bedingungslos.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | string | "" | Beim Setzen: eine gültige Media Query als String, z. B. "(prefers-color-scheme: dark)". Ein leerer String hebt die Einschränkung auf. |
Rückgabewert
media. Fehlt das Attribut, ist es ein leerer String.Beispiele
Media Queries aller theme-color-Tags auslesen
// HTML:
// <meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)">
// <meta name="theme-color" content="#1e1e1e" media="(prefers-color-scheme: dark)">
const metas = document.querySelectorAll('meta[name="theme-color"]');
metas.forEach((meta) => {
console.log(`${meta.content} → ${meta.media || '(immer)'}`);
});theme-color-Tag mit Media Query dynamisch erzeugen
const addThemeColor = (color, media = '') => {
const meta = document.createElement('meta');
meta.name = 'theme-color';
meta.content = color;
if (media) meta.media = media;
document.head.append(meta);
return meta;
};
addThemeColor('#f5f5f5', '(prefers-color-scheme: light)');
const dark = addThemeColor('#121212', '(prefers-color-scheme: dark)');
console.log(dark.outerHTML);Manueller Dark-Mode-Schalter in der App
// Die App erzwingt ein Farbschema, unabhängig von der Systemeinstellung
const setAppTheme = (mode) => {
const metas = document.querySelectorAll('meta[name="theme-color"]');
metas.forEach((meta) => {
const isDarkTag = meta.dataset.scheme === 'dark';
if (mode === 'system') {
meta.media = `(prefers-color-scheme: ${meta.dataset.scheme})`;
} else {
// passendes Tag immer gültig machen, das andere nie
meta.media = (mode === 'dark') === isDarkTag ? 'all' : 'not all';
}
});
};
// HTML: <meta name="theme-color" data-scheme="dark" content="#121212" ...>
document.querySelector('#theme-toggle')
?.addEventListener('click', () => setAppTheme('dark'));Prüfen, ob eine Media Query aktuell zutrifft
const active = [...document.querySelectorAll('meta[name="theme-color"]')]
.find((m) => !m.media || window.matchMedia(m.media).matches);
console.log('Aktive Theme-Farbe:', active?.content);// Wichtig · Fallstricke
- Nur für
theme-colorwirksam: Bei anderenname-Werten, z. B.viewportoderdescription, ignorieren Browser das Attributmedia. - Reihenfolge zählt: Treffen mehrere Tags zu, nimmt der Browser das erste passende im Dokument. Tags ohne
mediasollten deshalb am Ende stehen, als Rückfall. - Keine Validierung: Ungültige Media Queries werden ohne Fehlermeldung übernommen. Das Tag trifft dann nie zu. Zur Kontrolle eignet sich
window.matchMedia(meta.media).media. - Kompatibilität: Unterstützt in Chromium ab 93, Firefox ab 95 und Safari ab 15. Ob
theme-colorsichtbar wirkt, hängt aber von Plattform und Browser ab. Firefox auf dem Desktop zeigt die Farbe z. B. nicht an. Mobile Browser und installierte PWAs nutzen sie meist. - Die Eigenschaft ist ein reiner Spiegel des Attributs.
meta.media = ''setzt das Attribut auf einen leeren Wert, entfernt es aber nicht. Zum Entfernen dientremoveAttribute('media').