Container Queries

Zuletzt aktualisiert am 15. Februar 2026

Container Queries sind ein Paradigmenwechsel für CSS: Statt auf die Viewport-Breite zu reagieren, passen sich Elemente an die Größe ihres Containers an. Das macht Komponenten wirklich wiederverwendbar: eine Card-Komponente kann sich in einer schmalen Sidebar anders verhalten als im breiten Content-Bereich, ohne dass du etwas am CSS ändern musst.

Grundlagen

Bei Media Queries ist der Viewport die Bezugsgröße. Bei Container Queries ist es ein Eltern-Element, das du explizit als Container markierst. Die Kinder-Elemente können dann auf die Größe dieses Containers reagieren.

Damit ein Element als Container fungiert, brauchst du container-type. Der häufigste Wert ist inline-size, der die Breite des Containers abfragbar macht. size macht zusätzlich die Höhe abfragbar, ist aber selten nötig und hat Performance-Kosten. Mit container-name gibst du dem Container einen Namen, um bei verschachtelten Containern gezielt den richtigen anzusprechen.

Container Queries haben auch eigene Einheiten: cqw (1% der Container-Breite), cqh (1% der Container-Höhe), cqi (1% der Inline-Größe) und cqb (1% der Block-Größe). Damit kannst du Schriftgrößen und Abstände relativ zum Container skalieren.

Syntax & Werte

container-type

container-name & Shorthand

Container Query Units

Beispiele

Container Query Grundlagen

Eine Card wechselt von gestapeltem zu horizontalem Layout, wenn ihr Container breit genug ist.

.wrapper {
  container-type: inline-size;
}

.card {
  display: flex;
  flex-direction: column;
}

@container (min-width: 500px) {
  .card {
    flex-direction: row;
  }

  .card-image {
    width: 200px;
  }
}

<div class="cq-wrapper">
<div class="cq-card">
  <div class="cq-card-img"></div>
  <div class="cq-card-body">
    <h4>Container Query Card</h4>
    <p>Diese Card wechselt das Layout basierend auf der Container-Breite.</p>
  </div>
</div>
</div>

Gleiche Card in verschiedenen Containern

Die gleiche Card-Komponente passt sich automatisch an die Breite ihres Containers an, ohne dass du das CSS ändern musst.

/* Beide Spalten als Container */
.sidebar, .content {
  container-type: inline-size;
}

/* Die Card passt sich automatisch an */
.card { flex-direction: column; }

@container (min-width: 400px) {
  .card { flex-direction: row; }
}

<div class="cq-layout">
<div class="cq-col">
  <div class="cq-label">Schmale Sidebar</div>
  <div class="cq-item">
    <div class="cq-item-img"></div>
    <div class="cq-item-body">
      <h4>Gleiche Card</h4>
      <p>Passt sich an</p>
    </div>
  </div>
</div>
<div class="cq-col">
  <div class="cq-label">Breiter Content</div>
  <div class="cq-item">
    <div class="cq-item-img"></div>
    <div class="cq-item-body">
      <h4>Gleiche Card</h4>
      <p>Horizontal im breiten Container</p>
    </div>
  </div>
</div>
</div>

Benannte Container

Mit container-name sprichst du bei verschachtelten Containern gezielt den richtigen an.

.outer {
  container: layout / inline-size;
}

.inner {
  container: card-area / inline-size;
}

/* Reagiert auf den äußeren Container */
@container layout (min-width: 800px) {
  .badge { background: green; }
}

/* Reagiert auf den inneren Container */
@container card-area (min-width: 400px) {
  .text { font-size: 1.125rem; }
}

<div class="cq-named-outer">
<div class="cq-named-inner">
  <span class="cq-named-badge">Benannter Container</span>
  <h4>Verschachtelte Container</h4>
  <p>Reagiert auf den richtigen Container per Name.</p>
</div>
</div>

Container Query Units für Fluid Typography

cqw-Einheiten skalieren relativ zum Container: perfekt für Überschriften, die sich der verfügbaren Breite anpassen.

.container {
  container-type: inline-size;
}

.heading {
  /* Mindestens 1rem, maximal 2.5rem,
     skaliert mit 5% der Container-Breite */
  font-size: clamp(1rem, 5cqw, 2.5rem);
}

.text {
  font-size: clamp(0.875rem, 2.5cqw, 1.125rem);
}

<div class="cqu-demo">
<h3 class="cqu-heading">Fluid Typography</h3>
<p class="cqu-text">Diese Texte skalieren mit der Container-Breite. Ändere die Vorschau-Größe, um den Effekt zu sehen.</p>
</div>

Media Query vs. Container Query

Der direkte Vergleich: Media Queries reagieren auf den Viewport, Container Queries auf den Container.

/* Media Query: Viewport ist die Bezugsgröße */
@media (min-width: 768px) {
  .card { flex-direction: row; }
}

/* Container Query: Container ist die Bezugsgröße */
.wrapper { container-type: inline-size; }

@container (min-width: 500px) {
  .card { flex-direction: row; }
}

<div class="cq-compare">
<div class="cq-compare-col cq-compare-mq">
  <h4>@media</h4>
  <p>Reagiert auf Viewport</p>
  <span class="cq-compare-indicator mq-indicator">Viewport-abhängig</span>
</div>
<div class="cq-compare-col cq-compare-cq">
  <h4>@container</h4>
  <p>Reagiert auf Container</p>
  <span class="cq-compare-indicator cq-indicator">Container-abhängig</span>
</div>
</div>

Barrierefreiheit

Text, der mit cqw-Einheiten skaliert, kann in sehr schmalen Containern zu klein werden. Verwende immer clamp() mit einem Minimum in rem, um eine lesbare Mindestgröße zu garantieren: font-size: clamp(1rem, 5cqw, 2rem).

Wenn Container Queries das Layout ändern (z.B. von vertikal zu horizontal), stelle sicher, dass Touch-Targets (Buttons, Links) in beiden Layouts mindestens 44x44px groß bleiben. Ein Button, der im horizontalen Layout schrumpft, ist auf Touch-Geräten schwer zu treffen.

Häufige Fehler

• container-type vergessen. Ohne container-type: inline-size auf dem Eltern-Element funktioniert @container nicht. Die Kinder-Regeln werden einfach ignoriert.
• size statt inline-size verwenden. container-type: size macht auch die Höhe abfragbar, hat aber höhere Performance-Kosten und ist in den meisten Fällen unnötig. Verwende inline-size als Standard.
• Die Container Query auf den Container selbst anwenden statt auf die Kinder. @container ändert das Styling der Kind-Elemente, nicht des Containers. Der Container definiert nur die Bezugsgröße.
• Verschachtelte Container ohne Namen verwenden. Ohne container-name greift @container immer auf den nächsten Eltern-Container zu. Bei verschachtelten Containern kann das unerwartet sein. Benenne sie explizit.
• cqw-Einheiten ohne Minimum verwenden. font-size: 5cqw wird bei einem 200px-Container zu winzigen 10px. Verwende immer clamp() als Sicherheitsnetz.

Browser-Kompatibilität

Container Queries werden von allen modernen Browsern unterstützt. Safari unterstützt sie seit Version 16.0 (September 2022).

Email-Kompatibilität

Container Queries werden in keinem E-Mail-Client unterstützt.

Verwandte Eigenschaften