CSS-Variablen: von var() bis Themes und @property
Leitfaden zu CSS-Variablen (Custom Properties)
CSS-Variablen: Syntax, Scope, Themes, JavaScript, @property | We.Inc
CSS Custom Properties erklärt, mit einem Live-Theme in Hell und Dunkel, das nur aus Variablen besteht, getPropertyValue und setProperty in JavaScript, @property, Tailwind v4 @theme und typischen Stolperfallen.
Eine CSS-Variable deklarierst du mit zwei Bindestrichen, --brand: #2563eb;, meist innerhalb von :root, damit die ganze Seite sie sieht, und liest sie mit var(--brand). Ein zweites Argument ist der Fallback: var(--brand, blue). Variablen werden vererbt wie color, wenn du eine also in einem Abschnitt neu definierst, ändert sie sich für alles darin, und das macht Themes einfach.
Syntax auf einen Blick
- Aufgabe
- Code
- Global deklarieren
- :root { --gap: 1rem; }
- Verwenden
- padding: var(--gap);
- Fallback
- var(--gap, 16px)
- Lokal überschreiben
- .card { --gap: 0.5rem; }
- In JS lesen
- getComputedStyle(el).getPropertyValue('--gap')
- In JS schreiben
- el.style.setProperty('--gap', '2rem')
Dieser Leitfaden behandelt Deklaration, Scope und Fallbacks, dann einen Theme-Umschalter, bei dem sich nur Variablen ändern, ein Tool, das Variablen direkt auf dieser Seite per JavaScript liest und schreibt, registrierte Properties mit @property, wie Tailwind v4 sein Theme in Variablen umwandelt, und die Fehler, durch die var() stillschweigend scheitert.
- Schalte die Theme-Demo um. Das Markup ändert sich nie, nur die Werte von sechs Variablen.
- Wähle im JavaScript-Tool eine Variable, lies ihren aktuellen Wert, setze dann einen neuen und sieh zu, wie sich das Beispiel aktualisiert.
- Kopiere die Snippets unten für Tokens, Fallbacks und @property.
- Benenne Tokens nach ihrer Rolle, nicht nach ihrem Aussehen: --color-danger überdauert --red-500, wenn die Marke orange wird.
- Nutze ein zweistufiges System: rohe Palettenwerte und darüber semantische Tokens, die auf sie verweisen. Komponenten verwenden nur die semantische Ebene.
- Namen von Custom Properties unterscheiden Groß- und Kleinschreibung. --Brand und --brand sind zwei verschiedene Variablen.
- Nutze einen Fallback, wenn eine Komponente in einer Seite landen könnte, die deine Tokens nicht definiert.
Häufige Fragen
Was ist der Unterschied zwischen CSS-Variablen und Sass-Variablen?
Sass-Variablen werden beim Kompilieren des Stylesheets ersetzt und verschwinden aus der Ausgabe. CSS Custom Properties existieren zur Laufzeit im Browser, werden durch das DOM vererbt, können sich pro Element unterscheiden und lassen sich nach dem Laden der Seite per JavaScript oder durch eine Media-Query-Regel ändern.
Kann ich eine CSS-Variable in einer Media Query verwenden?
Nein. var() ist in der Bedingung einer @media-Regel nicht erlaubt, weil Media Queries ohne ein Element ausgewertet werden, von dem geerbt werden könnte. Du kannst aber den Wert einer Variable innerhalb eines Media-Query-Blocks ändern, und so macht man Tokens üblicherweise responsiv.
Warum funktioniert meine Variable nicht?
Prüfe Schreibweise und Groß- und Kleinschreibung, ob die Variable auf dem Element oder einem Vorfahren definiert ist und ob der endgültige Wert für die Eigenschaft gültig ist. Ist der eingesetzte Wert ungültig, wird die Deklaration zum Zeitpunkt des berechneten Werts ungültig, und die Eigenschaft fällt auf ihren geerbten oder Anfangswert zurück, nicht auf deine vorherige Regel.
Lassen sich CSS-Variablen animieren?
Eine nicht registrierte Variable wird als String behandelt, springt also in der Mitte um, statt weich überzublenden. Registriere sie mit @property und einer Syntax wie <color> oder <angle>, dann kann der Browser sie in Transitions und Animationen flüssig interpolieren.
Werden CSS-Variablen überall unterstützt?
Custom Properties und var() funktionieren seit Jahren in allen großen Browsern. @property ist neuer: Firefox hat es 2024 mit Version 128 eingeführt, prüfe also caniuse, wenn du ältere Versionen unterstützt, und behalte einen nicht registrierten Fallback.
Scope und Vererbung
- Eine Custom Property ist eine ganz normale vererbte Eigenschaft. Auf :root definiert, erreicht sie jedes Element. Auf .card definiert, gilt sie nur für diese Karte und ihre Nachfahren und schlägt dort den :root-Wert, weil der nähere Wert vererbt wird.
- Genau das macht Komponentenvarianten kurz. Ein Button liest var(--btn-bg), und .btn-danger setzt einfach --btn-bg: var(--color-danger). Kein zweiter Regelsatz für jeden Zustand.
Ungültig zum Zeitpunkt des berechneten Werts
- Der Browser kann eine var()-Deklaration beim Parsen nicht prüfen, weil der Wert erst beim Einsetzen bekannt ist. Daher wird margin: var(--size) mit --size: red beim Parsen akzeptiert und scheitert erst später.
- Scheitert es, wird die Eigenschaft wie unset behandelt. Bei einer vererbten Eigenschaft wie color bedeutet das die Farbe des Elternelements; bei margin bedeutet es 0. Eine frühere gültige margin-Regel in deinem Stylesheet kommt nicht zurück, was alle überrascht, die normale Fallbacks der Kaskade gewohnt sind.
Theme-Tokens in der Demo
Helle und dunkle Werte
- Token
- Hell
- Dunkel
- --color-bg
- --color-surface
- --color-text
- --color-muted
- --color-accent
- --color-border
Scope und Fallback live
Lokales Überschreiben und Fallback
Die zweite Karte definiert --accent für sich selbst neu. Die dritte nutzt eine Variable, die niemand definiert hat, daher erscheint die Fallback-Farbe.
Helles und dunkles Theme nur aus Variablen
Ein einziger Satz Komponentenregeln. Das Theme ist ein anderer Satz Werte, ausgewählt über die Systemeinstellung oder ein data-theme-Attribut.
Variablen in JavaScript lesen und schreiben
getPropertyValue und setProperty
Lies den berechneten Wert von jedem Element. Schreibe auf :root für eine globale Änderung oder auf ein einzelnes Element, um nur dessen Teilbaum zu beeinflussen.
@property: typisierte, animierbare Variablen
Einen Verlaufswinkel animieren
Wenn du --angle als <angle> registrierst, kann der Browser es interpolieren. Ohne Registrierung würde der Verlauf springen, statt sich zu drehen.
Tailwind v4 @theme
Tokens werden zu Utilities und Variablen
In Tailwind v4 erzeugen Variablen in @theme Utilities wie bg-brand und werden zusätzlich als echte CSS-Variablen ausgegeben, die du mit var() verwenden kannst.
Stolperfallen
Was Leute oft aus dem Tritt bringt
- Problem
- Warum
- Lösung
- var() in der @media-Bedingung
- Media-Bedingungen werden nicht pro Element ausgewertet
- Ändere stattdessen die Variable innerhalb des Media-Blocks
- Wert mit Einheit scheitert
- --n: 4; dann ergibt width: var(--n)px '4 px'
- Nutze calc(var(--n) * 1px)
- Eigenschaft fällt auf den Anfangswert zurück
- Ungültig zum Zeitpunkt des berechneten Werts
- Prüfe den eingesetzten Wert, füge einen Fallback hinzu
- Variable in url() ignoriert
- url(var(--x)) ist nicht erlaubt
- Speichere das ganze url(...) in der Variable
- Abgeleitete Variable ignoriert ein Überschreiben
- :root { --big: calc(var(--base) * 2) } wird auf :root aufgelöst, daher ändert .card { --base: 5px } nichts an --big
- Deklariere --big auch auf .card neu oder berechne es dort, wo es verwendet wird
Helles und dunkles Theme, nur mit Variablen
Theme
Heller Modus
Dunkler Modus
Wochenbericht
Mehr Bestellungen als letzte Woche
Beispielbestellungen
Details ansehen
Das Einzige, was sich ändert
CSS kopieren
Variablen per JavaScript lesen und schreiben
Die Beispielbox unten nutzt var(--demo-accent, #2563eb) für ihren Rahmen und var(--demo-radius, 8px) für ihre Ecken. Setze eine der beiden Variablen und die Box ändert sich.
Variablenname
Neuer Wert
Der Name einer Custom Property beginnt mit zwei Bindestrichen, zum Beispiel --demo-radius.
Lesen
Setzen
Entfernen
Probiere --demo-radius
Beispielbox
(nicht gesetzt)
Kostenlos starten · Keine Kreditkarte nötig
Verwandt: Ratgeber
- CSS z-index und Stacking Contexts, in 3D zerlegt
- Dark Mode für Websites
- Data Fetching in React und Next.js im Vergleich
- Data-URLs
- Debounce vs. Throttle, visualisiert
- Deferred Deep Linking einfach erklärt
- Microsites für Abteilungen
- React- oder Next.js-App deployen
Produkt
Für wen
- Für Agenturen
- Für Freelancer
- Für Hosting-Anbieter
- Für SaaS-Plattformen
- Für Start-ups
- Finanzdienstleistungen
- Lösungen für das Gesundheitswesen
Funktionen
Ressourcen
- Blog
- Hilfecenter
- Kostenlose Tools für Unternehmen
- Free UI Components
- Vorlagen
- Vorlagen-Sammlungen
- Website-Beispiele
- Ratgeber
- Vergleiche
- Alternativen
- Die besten
- Testberichte
- Preisübersichten
- Anwendungsfälle
- Glossar und Anleitungen
- Integrationen
- Entwickler
- Benchmark
- Windows App