CSS Container Queries : adapter un composant à son conteneur

Ce que vous saurez faire

Choisir entre media query et container query, nommer un contexte dans une interface imbriquée et utiliser les unités relatives au conteneur sans rendre le composant fragile.

1. Le breakpoint appartient au composant

Une media query est pertinente quand la composition globale dépend de la fenêtre : navigation mobile, nombre de colonnes d’une page, préférences du périphérique, etc.

Une container query devient plus naturelle quand la règle appartient au composant :

.product-slot {
  container: product / inline-size;
}

.product-card {
  display: grid;
  gap: 1rem;
}

@container product (width >= 30rem) {
  .product-card {
    grid-template-columns: minmax(8rem, 12rem) 1fr;
    align-items: start;
  }
}

Cette carte peut maintenant vivre dans une grille, une modale ou une colonne secondaire sans que son CSS contienne un breakpoint lié à la largeur de la page.

Référence : MDN — CSS container queries.

2. Pourquoi inline-size est souvent préférable à size

container-type: size permet d’interroger les deux dimensions, largeur et hauteur. Il applique aussi un containment de taille dans les deux axes : le navigateur doit pouvoir calculer la taille du conteneur indépendamment de ses enfants.

Pour un composant qui ne réagit qu’à l’espace horizontal, inline-size est généralement plus adapté : il limite le containment à cet axe et répond directement au besoin.

La taille du conteneur doit néanmoins provenir du contexte — par exemple un bloc qui s’étire dans sa colonne, une piste de grille ou une largeur explicite. Avec du size containment et aucune taille déterminable, un élément peut se retrouver sans la dimension que son contenu lui aurait normalement donnée.

Référence : MDN — container-type.

3. Les noms évitent les mauvaises correspondances

Dans un composant imbriqué, plusieurs ancêtres peuvent être des query containers. Sans nom, le navigateur utilise le plus proche qui convient au type de requête.

.dashboard {
  container: dashboard / inline-size;
}

.widget-list {
  container: widgets / inline-size;
}

@container widgets (width >= 40rem) {
  .widget-card {
    grid-template-columns: 1fr 1fr;
  }
}

Le nom widgets documente précisément la dimension à laquelle la carte doit répondre. C’est particulièrement utile lorsqu’un composant possède lui-même des sous-composants responsives.

4. Les unités cqi suivent le conteneur

CSS fournit aussi des unités relatives au query container. 1cqi représente 1 % de sa taille dans l’axe inline.

@container product (width >= 24rem) {
  .product-card h2 {
    font-size: clamp(1.1rem, 1rem + 2cqi, 1.8rem);
  }
}

Le titre peut ainsi évoluer doucement avec l’espace réellement disponible, tout en restant borné par clamp().

Ne transformez pas toutes les dimensions en unités de conteneur. Les tailles de police de base, espacements et zones tactiles ont souvent intérêt à rester stables ; utilisez les unités cq* lorsque la relation avec la taille du composant apporte réellement quelque chose.

5. Construire d’abord une base robuste

Une container query doit améliorer un composant déjà utilisable dans son état par défaut :

.card {
  display: grid;
  gap: 1rem;
}

@container cards (width >= 36rem) {
  .card {
    grid-template-columns: 12rem 1fr;
  }
}

La première règle reste valide dans un espace étroit. La requête ne sert qu’à changer la composition quand davantage de place existe. Cette progression rend le composant plus prévisible et simplifie aussi la prise en charge d’environnements plus anciens lorsque celle-ci compte pour votre projet.

Pièges importants

• Ne choisissez pas les seuils à partir de modèles de téléphone : choisissez-les au moment où le composant a réellement assez d’espace pour changer de composition.
• Une requête de taille nécessite un conteneur de taille compatible ; un simple container-name ne suffit pas pour interroger sa largeur.
• Les styles de la requête ciblent les descendants du conteneur interrogé, pas ce conteneur lui-même.
• size ajoute plus de contraintes que inline-size; ne l’utilisez que si vous devez réellement interroger les deux axes.
• Les container queries complètent les media queries : elles ne les rendent pas obsolètes.

Mémo final

Utilisez les media queries pour les décisions qui appartiennent à la page ou au périphérique. Utilisez les container queries pour les décisions qui appartiennent au composant. Cette séparation produit des composants plus autonomes, plus faciles à déplacer et plus proches de la logique réelle d’un design system.