Custom Media Queries: @custom-media in PostCSS vs. natives CSS

1. Das Grundproblem: dieselbe Breitenangabe an zwanzig Stellen

In einem gewachsenen Stylesheet taucht ein Breakpoint wie min-width: 48rem oft an Dutzenden Stellen auf, verstreut über verschiedene Komponenten-Dateien. Ändert sich der Breakpoint, weil das Designteam die Tablet-Grenze anpasst, muss diese Zahl an jeder einzelnen Stelle manuell gesucht und ersetzt werden, mit dem Risiko, eine Stelle zu übersehen und eine inkonsistente Darstellung zu produzieren.

Custom Media Queries lösen genau dieses Problem, indem sie eine Bedingung wie --breakpoint-tablet genau einmal definieren und danach per Namen referenzieren. Das ist konzeptionell dasselbe, was Custom Properties für Farbwerte oder Abstände leisten, nur eben auf Ebene ganzer Media-Query-Bedingungen statt einzelner Werte.

2. @custom-media in PostCSS: Syntax und Grundeinrichtung

Mit dem PostCSS-Plugin postcss-custom-media wird eine benannte Bedingung mit der At-Regel @custom-media deklariert, typischerweise in einer zentralen Datei, die vor allen anderen Stylesheets eingebunden wird. Der Name beginnt zwingend mit zwei Bindestrichen, genau wie bei Custom Properties, und kann danach in jeder @media-Regel des Projekts als Bedingung eingesetzt werden.

Beim Build-Schritt ersetzt PostCSS jede Verwendung von @media (--breakpoint-tablet) durch die tatsächliche, ausgeschriebene Bedingung, sodass der ausgelieferte CSS-Code am Ende ganz normale, von jedem Browser verstandene Media Queries enthält. Für das Entwicklungsteam bleibt im Quellcode aber der sprechende Name erhalten, was Lesbarkeit und Wartbarkeit deutlich erhöht.

/* breakpoints.css -- zentral definiert, vor allen anderen Dateien geladen */
@custom-media --breakpoint-tablet (min-width: 48rem);
@custom-media --breakpoint-desktop (min-width: 64rem);
@custom-media --dark-mode (prefers-color-scheme: dark);

/* component.css -- Verwendung an beliebig vielen Stellen */
.sidebar {
  display: none;
}

@media (--breakpoint-tablet) {
  .sidebar {
    display: block;
  }
}

3. Bedingungen kombinieren: and, or und verschachtelte Custom Media Queries

Ein besonderer Vorteil von @custom-media ist, dass sich mehrere benannte Bedingungen mit and oder or kombinieren lassen, ohne die zugrunde liegende Definition doppelt auszuschreiben. Eine Bedingung wie Tablet oder größer, aber nicht im Dunkelmodus lässt sich dadurch lesbar formulieren, statt eine lange, schwer verständliche einzelne Media-Query-Kette zu pflegen.

PostCSS erlaubt außerdem, eine Custom Media Query innerhalb der Definition einer anderen zu verwenden, was hierarchische Bedingungen wie Desktop, was Tablet einschließt ermöglicht. Diese Verschachtelung sollte allerdings sparsam eingesetzt werden, weil sie schnell unübersichtlich wird, wenn eine Bedingung über mehrere Ebenen hinweg aus anderen Bedingungen zusammengesetzt ist.

@custom-media --breakpoint-tablet (min-width: 48rem);
@custom-media --dark-mode (prefers-color-scheme: dark);

@media (--breakpoint-tablet) and not (--dark-mode) {
  .banner {
    background: #ede9fe;
  }
}

@media (--breakpoint-tablet) or (--dark-mode) {
  .contrast-note {
    display: block;
  }
}

4. Der native Weg: Custom Media Queries in Media Queries Level 5

Die Spezifikation Media Queries Level 5 definiert dieselbe At-Regel @custom-media nativ für den Browser, mit nahezu identischer Syntax zu PostCSS. Sobald ein Browser diese Regel unterstützt, muss keine Build-Zeit-Übersetzung mehr stattfinden, weil der Browser die Bedingung selbst zur Laufzeit auflöst und bei jeder Verwendung von @media (--breakpoint-tablet) die hinterlegte Definition direkt anwendet.

Der praktische Unterschied zur PostCSS-Variante liegt vor allem darin, dass native Custom Media Queries auch nachträglich per JavaScript oder über CSS Custom Properties beeinflussbar werden könnten, sobald die Spezifikation entsprechend erweitert wird, während eine PostCSS-Bedingung als Build-Zeit-Konstante feststeht und sich zur Laufzeit im Browser nicht mehr ändern lässt.

5. Browser-Unterstützung heute und die realistische Zeitschiene

Zum jetzigen Stand unterstützt kein aktueller Browser die native @custom-media-Regel vollständig produktionsreif, sie befindet sich in unterschiedlichen Experimentierstadien hinter Flags oder in frühen Implementierungen. Ein produktives Projekt kann sich also nicht allein auf die native Unterstützung verlassen, sondern muss weiterhin auf PostCSS oder eine vergleichbare Build-Zeit-Lösung setzen, um Custom Media Queries schon heute nutzbar zu machen.

Für die Projektplanung bedeutet das: Wer heute mit postcss-custom-media arbeitet, verwendet bereits exakt die Syntax, die später nativ funktionieren wird, weil beide Spezifikationen bewusst aufeinander abgestimmt sind. Das minimiert das Migrationsrisiko erheblich, weil kein Syntaxwechsel nötig sein wird, sondern lediglich der Build-Schritt irgendwann entfallen kann.

6. Migrationsstrategie: vom PostCSS-Plugin zum nativen Browser-Feature

Der empfohlene Weg ist, alle Custom-Media-Definitionen von Anfang an in einer einzigen, zentralen Datei zu bündeln, statt sie über das gesamte Projekt zu verteilen. Das macht die spätere Migration zu einer Ein-Datei-Änderung: Sobald native Unterstützung in allen relevanten Zielbrowsern gegeben ist, wird das PostCSS-Plugin einfach aus der Build-Pipeline entfernt, ohne dass an den Definitionen selbst etwas geändert werden muss.

Wichtig ist außerdem, in dieser Übergangszeit auf @supports-Prüfungen zu verzichten, weil sich @custom-media im PostCSS-Fall ohnehin vollständig in reguläre @media-Regeln auflöst, bevor der Code den Browser erreicht. Der Feature-Test wird erst relevant, sobald tatsächlich mit einer gemischten Codebasis aus nativer und noch nicht übersetzter Syntax gearbeitet wird, was in einem gut geplanten Migrationsprojekt in der Regel vermieden werden sollte.

# Vorher: PostCSS uebernimmt die Aufloesung im Build
npm install postcss-custom-media --save-dev

# postcss.config.js
module.exports = {
  plugins: [
    require('postcss-custom-media'),
    require('autoprefixer'),
  ],
};

# Nachher, sobald native Unterstuetzung ausreicht:
# Plugin-Zeile einfach aus postcss.config.js entfernen,
# @custom-media-Definitionen bleiben unveraendert bestehen.

7. Custom Media Queries neben Tailwind CSS: sinnvolle Ergänzung, kein Ersatz

In einem Projekt mit Tailwind CSS decken die eingebauten Breakpoint-Präfixe wie md: oder lg: bereits den größten Teil des Anwendungsfalls ab, weil sie exakt dasselbe Ziel verfolgen: benannte, konsistent wiederverwendbare Bedingungen statt ausgeschriebener Breitenangaben. Custom Media Queries werden dort relevant, wo Bedingungen jenseits reiner Breakpoints stehen, etwa eine Kombination aus prefers-reduced-motion und einer Mindestbreite, die als eigene, wiederverwendbare Einheit benannt werden soll.

Auch in handgeschriebenem CSS außerhalb des Utility-Frameworks, etwa für komplexe Komponenten-Bibliotheken oder Design-System-Basis-Stylesheets, bleibt @custom-media das richtige Werkzeug, um Bedingungen genauso konsistent zu benennen wie Farb- und Abstandswerte über Custom Properties.

8. Namenskonventionen: semantische Namen statt reiner Pixelwerte

Ein häufiger Anfängerfehler ist, Custom Media Queries nach ihrem Zahlenwert zu benennen, etwa --bp-768, statt nach ihrer eigentlichen Bedeutung im Design-System. Ändert sich später der zugrunde liegende Breitenwert, weil das Designteam den Tablet-Breakpoint von 48rem auf 50rem verschiebt, bleibt der Name --bp-768 plötzlich inhaltlich falsch, obwohl er im Code unverändert weiterverwendet wird und dadurch für Verwirrung sorgt.

Bewährt hat sich stattdessen eine semantische Benennung nach Zweck statt nach Wert, etwa --breakpoint-tablet oder --breakpoint-nav-collapse, die auch dann noch korrekt bleibt, wenn sich der konkrete Zahlenwert dahinter ändert. Dieselbe Konvention gilt für funktionale Bedingungen wie --dark-mode oder --reduced-motion, die den Zweck der Bedingung beschreiben, statt die zugrunde liegende Media-Feature-Syntax im Namen zu wiederholen.

/* Ungünstig: Name koppelt sich an einen konkreten Zahlenwert */
@custom-media --bp-768 (min-width: 48rem);

/* Besser: Name beschreibt den Zweck, bleibt bei Wertaenderung korrekt */
@custom-media --breakpoint-tablet (min-width: 48rem);
@custom-media --breakpoint-nav-collapse (max-width: 61.9375rem);
@custom-media --reduced-motion (prefers-reduced-motion: reduce);

9. PostCSS-Ansatz und nativer Standard im direkten Vergleich

Beide Wege führen syntaktisch zum selben Ergebnis, unterscheiden sich aber in Zeitpunkt der Auflösung, Browser-Abhängigkeit und den daraus entstehenden praktischen Konsequenzen für Build-Pipeline und Debugging.

10. Zusammenfassung

11. FAQ: Custom Media Queries: Das Wichtigste auf einen Blick