Contexte d’empilement CSS : pourquoi votre z-index ne marche pas

Qu’est-ce qu’un contexte d’empilement ?

Un contexte d’empilement est un groupe d’éléments peints ensemble comme une seule unité. À l’intérieur, c’est le z-index qui décide de l’ordre ; à l’extérieur, le groupe entier est placé comme un seul élément et ses enfants ne peuvent pas s’en échapper. Cette phrase est derrière presque tous les bugs de z-index : un enfant à 999999 ne rivalise pas avec le reste de la page, seulement avec ses frères et sœurs dans le même contexte.

L’autre moitié de la confusion est que le z-index ne fait souvent rien du tout. CSS 2.2 donne à la propriété une ligne « s’applique à » qui dit éléments positionnés : sur un élément statique, ce n’est donc pas une déclaration faible, elle n’est pas appliquée. Voilà pourquoi augmenter le nombre n’aide jamais.

Cet outil répond aux deux questions à partir du CSS que vous collez, et nomme la spécification derrière chaque réponse, car les règles sont réparties dans sept documents différents et aucun ne les réunit toutes.

Comment s’en servir

1. Collez les déclarations de l’élément. Une par ligne ou séparées par des points-virgules. Les trois boutons d’exemple couvrent les cas les plus courants : un z-index silencieusement ignoré, une opacité qui crée un contexte auquel personne ne s’attend, et une modale fixe qui piège tout ce qu’elle contient.
2. Indiquez ce qu’est le parent. Bloc, flex ou grid. Cela compte plus qu’il n’y paraît : le même z-index est inerte dans un parent de bloc et fonctionne dans un parent flex ou grid, et cette seule commande fait toute la différence entre les deux réponses.
3. Lisez les deux verdicts, puis les raisons. Le premier dit si le z-index s’applique. Le second dit si cet élément piège ses descendants, chaque cause étant accompagnée de la spécification qui la définit.

L’exception flex et grid que presque tout le monde rate

La règle que chacun a en tête est que le z-index ne fonctionne que sur les éléments positionnés. Elle est presque juste, et l’exception est écrite dans deux spécifications avec les mêmes mots. CSS Flexbox indique que, pour les éléments flex, des valeurs de z-index autres que auto créent un contexte d’empilement même si position vaut static. CSS Grid reprend la phrase exacte pour les éléments grid.

La même déclaration se comporte donc de deux façons selon le parent. Dans un conteneur de bloc ordinaire, un élément statique avec z-index: 999999 est inerte et ne crée aucun contexte. Déplacez cet élément dans un conteneur flex sans toucher un seul caractère de son propre CSS, et le z-index s’applique désormais et crée un contexte. Cet outil dispose d’une commande pour le parent uniquement pour cette raison : c’est la seule entrée qui change la réponse sans changer le CSS.

Il existe une surprise jumelle de l’autre côté. Avec z-index laissé à auto, relative et absolute ne créent aucun contexte d’empilement, tandis que fixed et sticky en créent toujours un. La spécification de positionnement CSS le dit sans détour : les boîtes en position fixe ou collante forment malgré tout un contexte d’empilement. La moitié des valeurs de position se comporte donc d’une façon et l’autre moitié d’une autre, précisément sur la valeur qu’on ne définit jamais exprès.

La plus invisible : l’opacité

Des dix-sept causes que cette page recense, l’opacité est celle qu’il faut retenir, car rien à l’écran ne la trahit. Un élément avec opacity: 0.999 ressemble exactement à un élément avec opacity: 1 — impossible de les distinguer à quelque zoom que ce soit — et pourtant le premier crée un contexte d’empilement et le second non. Tous les descendants se retrouvent piégés d’un coup, et un menu déroulant qui passait au-dessus de l’en-tête passe désormais derrière.

Le même piège prend plusieurs autres formes. Un transform quel qu’il soit, un filter, un backdrop-filter, un clip-path, un masque, un mix-blend-mode autre que normal, isolation: isolate, contain avec paint ou layout, et un will-change nommant l’une de ces propriétés créent tous un contexte. Plusieurs sont ajoutés pour la performance ou pour un effet au survol, par quelqu’un qui ne pensait pas du tout à l’ordre de peinture.

C’est pourquoi la solution à un z-index bloqué n’est presque jamais un nombre plus grand. C’est de trouver l’ancêtre qui piège et de décider s’il le devrait. L’outil signale toutes les causes qu’il trouve, pas la première, car un élément en cumule fréquemment trois ou quatre et n’en retirer qu’une ne change rien.

Limites assumées

Ceci examine un élément à la fois. Le contexte d’empilement est une propriété d’un élément, mais le bug est une propriété de l’arbre : pour savoir si votre modale est piégée, il faut remonter ses ancêtres un par un, et l’outil ne les voit pas depuis un seul bloc de CSS. Ce qu’il vous donne, c’est la réponse par élément, à emporter en remontant.

Il lit les déclarations littéralement et ne résout ni la cascade, ni les propriétés personnalisées, ni les raccourcis, ni les media queries. Si votre opacité provient d’une classe que vous n’avez pas collée, ou d’un var() défini ailleurs, il ne peut pas le savoir. Collez les styles calculés depuis l’inspecteur de votre navigateur si vous voulez une certitude.

La liste des causes est l’ensemble défini par les spécifications citées en regard de chaque ligne, et elle n’est pas figée : les spécifications CSS continuent d’y ajouter. contain et will-change sont deux ajouts récents, et aucun document normatif unique ne les recense toutes — c’est précisément pourquoi chaque ligne porte sa propre citation plutôt que de renvoyer à une seule page.

Les noms de spécifications restent en anglais sur toutes les versions linguistiques de cette page, car ce sont des identifiants de document et non de la prose. Qui veut en consulter une a besoin de la chaîne publiée par l’organisme.

Pourquoi est-ce gratuit ?

C’est de l’analyse de texte, et elle s’exécute dans votre navigateur. Aucun serveur n’intervient : rien à facturer, aucun compte à créer.

Rien n’est envoyé et rien n’est conservé. Rechargez la page et elle aura oublié votre CSS.