`@container` - Directive CSS

@container

Résumé des caractéristiques de la directive `@container`

Description rapide

Permet d'écrire des règles CSS conditionnelles en fonction des caratéristiques du conteneur.

Statut

Standard

Module W3C

Module CSS - Confinement

Références (W3C)

CSS Containment Module Level 3

Statut du document: WD (document de travail)

Description de la directive `@container`.

La directive @container introduit la possibilité d'écrire des styles conditionnels en fonction des dimensions d'un élément.
Le terme anglais est container query.

De même que les media queries (voir la directive @media) permettent d'adapter les styles en fonction des caractéristiques du terminal : dimensions du viewport, orientation de l'écran, etc. les container queries considèrent les caractéristiques d'un élément de la page (le conteneur) pour appliquer ou non des styles à ses éléments enfants.

Remarque : une requête container queries ne peut appliquer des styles que aux enfants de l'élément qui a été déclaré comme le conteneur. Ce dernier, le conteneur lui même, ne peut pas être stylé dans une requête container queries le concernant.

Dans ce premier exemple, le logo de Firefox est une image flottante sur la gauche, ce qui permet d'avoir la description à côté de l'image.
Mais si la largeur du conteneur est insuffisante, les lignes de texte situées à côté de l'image vont être très courtes, rendant la lecture difficile.
La largeur du conteneur peut être contrainte par la mise en page : par exemple ce conteneur peut être dans une cellule de grille contenant d'autres éléments et dont la largeur des colonnes est dynamique.
Pour les besoins de la démonstration, nous avons rendu la largeur du conteneur ajustable avec la souris.

Dans ce deuxième exemple, une requête container query a été utilisée pour rendre l'image non flottante lorsque la largeur du conteneur est insuffisante (inférieure à 200 pixels).
Comme ci-dessus, vous pouvez ajuster la largeur du conteneur avec la souris pour simuler une contrainte due à la mise en page.

Éléments de syntaxe :

Tout débord il faut définir quel élément est le conteneur, et de quel type de conteneur il s'agit. Cela peut se faire avec les propriétés container-name et container-type ou plus simplement avec la propriété résumée container.
Pour l'exemple ci-dessus, nous avons défini que le nom du container est demo et qu'il agit suivant l'axe des lignes. L'image est également déclarée flottante à gauche par défaut.


	#description1b {
	   container-name: demo;
	   container-type: inline-size;
	}
	#description1b img {
	   float:left; 
	   margin-right:10px;
	}

Remarque : l'identifiant du conteneur peut être défini sur une classe, donc pas forcément pour un élément unique.

Il faut ensuite écrire la requête container query proprement dite. Celle-ci ne peut faire référence que à des éléments enfants du conteneur. Ici nous déclarons que l'image n'est plus flottante si la largeur du conteneur est inférieure à 200 pixels.


	@container demo (width < 200px) {
	   #description1b img {
	      float:none; 
	      margin-right:200px;
	   }
	}

Autres exemples.

On sait que le texte justifié n'est pas très esthétique sur des lignes courtes : cela provoque des espaces exagérément grands entre les mots. Une requête container query a été utilisée pour aligner le texte à gauche lorsque la largeur du conteneur est inférieure à 300 pixels.

Ici la direction d'écriture s'adapte en fonction de la forme du conteneur : s'il est plus large que haut, l'écriture est horizontale, et verticale s'il est plus haut que large.

Unités spécifiques aux container queries.

Plusieurs unités ont été créées pour exprimer des dimensions en fonction des dimensions de l'élément conteneur. Reportez-vous à la page sur les unités de dimension relatives au conteneur.

Avantages des requêtes container queries.

Le principal avantage des container queries est de permettre la mise en forme d'un élément indépendamment du reste de la page. C'est particulièrement utile pour des composants, qui peuvent être insérés dans une page dont la mise en page est inconnue.

Les requêtes type `scroll-state`. ⚠

Ces requêtes permettent de s'informer sur l'état de défilement du container : peut-il défiler encore dans une direction ou une autre ? S'agit-il d'un container avec accrochage (défilement avec accrochages) ? Et enfin, pour les container en position sticky, est-ce que le container est bloqué à une extrémité de l'écran, et laquelle ?

Les requêtes style container queries. ⚠

Cette évolution des container queries permet de tester n'importe quelle propriété de l'élément conteneur. C'est la valeur calculée de la propriété qui est prise en compte.
Mais cette fonctionnalité est encore peu prise en charge.

Exemples de syntaxes pour `@container`.

Les exemples très simples donnés ici sont constitués d'un élément conteneur qui sert au confinement, et d'un élément interne sur lequel les propriétés sont ajustées. Il n'est pas possible en effet de changer les propriétés du conteneur lui-même.

@container id (width > 200px) and (width < 400px) { ... }

Ceci est la syntaxe de base d'une requête container query.
- id est un identifiant facultatif. Il aura été défini par le propriété container-name ou container sur un ou plusieurs des éléments de la page.
  S'il n'est pas renseigné, la requête s'applique à tous les conteneurs de la page.
- (width > 200px) est une condition faisant intervenir une propriété et une valeur. C'est la valeur calculée de la propriété qui est prise en compte.
- and, or ou not sont des opérateurs permettant de combiner plusieurs conditions, chacune des conditions étant inscrites entre parenthèses.
Les propriétés utilisables dans les conditions sont :
- width et height : largeur ou hauteur de l'élément conteneur.
- inline-size et block-size : dimension de l'élément conteneur dans la direction des lignes, ou dans la direction des blocs.
- aspect-ratio : ratio correspondant à la largeur de l'élément conteneur divisé par sa hauteur.
- orientation : prend la valeur landscape si la largeur de l'élément conteneur est plus grande que sa hauteur, et la valeur portrait dans le cas contraire.
Les tests sur la hauteur (height), la dimension dans la direction des blocs (block-size), le ratio et l'orientation ne sont prises en charge que sur les conteneurs de type size (voir container-type).

Ce texte passe en rouge dès que la largeur est inférieure à 150 pixels.

Ce texte passe en rouge dès que son orientation est en portrait. Nous avons écrit not(orientation:landscape) Ce qui renvient au même. Changez ses dimensions pour constater.

Ce texte passe en rouge dès que sa largeur est inférieure à sa hauteur. Changer ses dimensions pour le constater.

Les navigateurs reconnaissent en principe une autre syntaxe, héritée du passé, et qui est moins lisible que la précédente. Voici cette ancienne syntaxe, avec les équivalences.

@container id ((min-width: 200px) and (max-width: 400px)) { sélecteur { propriétés CSS } }

min-width: valeur

⇔

width > valeur

max-width: valeur

⇔

width < valeur

min-height: valeur

⇔

height > valeur

max-height: valeur

⇔

height < valeur
@container id scroll-state(stuck:top) { ... }

Le descripteur stuck n'est actif que sur les éléments dont la propriété position est sticky. Utilisé avec la fonction scroll-state(), il s'active lorsque l'élément conteneur est "collé" par l'un de ses bords :
- none : l'élément stuck ne joue aucun rôle.
- top : l'élément est collé au bord supérieur.
- right : l'élément est collé au bord droit.
- bottom : l'élément est collé au bord inférieur.
- left : l'élément est collé au bord gauche.
- block-start : l'élément est collé au bord correspondant au début des blocs.
- block-end : l'élément est collé au bord correspondant à la fin des blocs.
- inline-start : l'élément est collé au bord correspondant au début des lignes.
- inline-end : l'élément est collé au bord correspondant à la fin des lignes.
Le type de container (container-type) doit être scroll-state.

L'exemple ci-dessous est composé d'un bloc de confinement (id=stuck-container), qui contient un élément de texte (id=stuck-element). Le bloc de confinement est position:sticky, il reçoit les propriétés container-type, fixée à scroll-state, et un identifiant définir par container-name. L'élément reçoit la couleur rouge lorsque sticky:bottom.
Faites défiler la page vers le haut pour coller le bloc au bas de l'écran.

⚠ Cela ne marche pas sur tous les navigateurs.

Ce texte passe en rouge dès qu'il est collé par son bord inférieur.
@container id scroll-state(scrollable: top) { ... }

Le descripteur scrollable s'active lorsque le conteneur peut faire l'objet d'un défilement (présence d'une barre de défilement et contenu dépassant la taille du conteneur).
- none : l'élément scrollable ne joue aucun rôle.
- top : l'élément eut être défilé vers le haut.
- right : l'élément peut être défilé vers la droite.
- bottom : l'élément peut être défilé vers le bas.
- left : l'élément peut être défilé vers la gauche.
- x : l'élément peut être défilé dans le sens horizontal.
- y : l'élément peut être défilé dans le sens vertical.
- block-start : l'élément est collé au bord correspondant au début des blocs.
- block-end : l'élément est collé au bord correspondant à la fin des blocs.
- inline-start : l'élément est collé au bord correspondant au début des lignes.
- inline-end : l'élément est collé au bord correspondant à la fin des lignes.
- block : l'élément peut être défilé ans le sens des blocs.
- inline : l'élément peut être défilé dans le sens des lignes.
Ici aussi, le type de container doit être scroll-state.

L'élément principal est le conteneur de confinement (id=scroll-container). Il contient un élément (id=scroll-element) avec un texte assez long pour nécessiter un défilement. Deux requêtes container query affichent l'élément bleu lorsque le défilement vers le haut n'est plus possible, et en rouge lorsque le défilement vers le bas n'est plus possible. Rappelons que ces requêtes ne peuvent agir que sur un descendant du conteneur de confinement.

⚠ Cela ne marche pas sur tous les navigateurs.

Ce texte passe en bleu lorsqu'il n'est plus possible de le faire défiler vers le haut, et en rouge dès qu'il n'est plus possible de le faire défiler vers le bas. Cela a nécessité deux requêtes container query.
@container id scroll-state(snapped: block) { ... }

Le descripteur snapped permet de tester si le conteneur de confinement est ancré. Il faut donc qu'il se trouve dans un conteneur avec un ancrage sur le défilement.
- none : l'élément snapped ne joue aucun rôle.
- x : le conteneur est un élément avec accrochage suivant X.
- y : le conteneur est un élément avec accrochage suivant Y.
- block : le conteneur est un élément avec accrochage suivant l'axe des blocks..
- inline : le conteneur est un élément avec accrochage suivant l'axe des lignes.
- both : le conteneur est un élément avec accrochage suivant les deux axes.
Ici le conteneur de confinement est multiple. Il a la capacité de s'ancrer lors du défilement (scroll-snap-align:center). Il reçoit bien sûr les propriété container-name et container-type qui en font un conteneur de confinement, plus quelques autres propriétés de mise en forme.
Au dessus, se trouve le conteneur de défilement avec ancrage (id=container) avec la propriété scroll-snap-type:y mandatory.
Si nécessaire, reportez-vous au tutoriel sur défilements avec accrochages.

En utilisant la barre de défilement, vous ancrez successivement chacun des éléments. Celui qui est ancré prend un fond coloré.

⚠ Cela ne marche pas sur tous les navigateurs.

1

2

3

4
@container id style(propriété:valeur) { ⚠ ... }

La fonction style() permet de tester la présence d'une propriété qui serait appliquée au conteneur, directement ou par le biais d'un héritage. Pour l'instant (2025) cela ne marche que avec des propriétés personnalisées.

⚠ Cela ne marche pratiquement sur aucun navigateurs.

Ce texte passe en rouge dès que son alignement centré.

Ce deuxième paragraphe n'est pas centré.

Prise en charge par les navigateurs (compatibilité).

La directive @container est bien reconnue pour ce qui est des tests sur les dimensions du conteneur, mais pas encore pour les tests de défilement avec scroll-state(), ni sur les tests de styles avec styles().

Colonne 1

Traitement correct par les navigateurs de la directive @container qui facilite beaucoup l'écriture de composants.

Colonne 2

Reconnaissance par les navigateurs de la fonction scroll-state() avec la directive @container.

Colonne 3

Reconnaissance par les navigateurs de la fonction style() dans la syntaxe de la directive @container.

Directive
@container

Fonction scroll-state()
dans @container

Fonction style()
dans @container

Estimation de la prise en charge globale.

92%

63%

Navigateurs sur ordinateurs :

Navigateurs sur mobiles :

Navigateurs obsolètes ou marginaux :

Internet Explorer

UC Browser pour Androïd

Safari

Safari sur IOS

Opéra Mobile

QQ Browser

Baidu Browser

Chrome

Edge

Firefox

Opéra

Chrome pour Androïd

Samsung Internet

Androïd Brower

Firefox pour Androïd

KaiOS Browser

Opéra mini

Voir le site Caniuse.com pour plus d'informations de compatibilité.

Caniuse

Évolution de la directive `@container`.

Module CSS - Confinement - Niveau 3

Introduction des techniques de "confinement" et de la directive @container.

21 Décembre 2021
Document de travail.