Z-index
Control local stacking order or place custom elements on the shared component layers.
Syntax
Use a z-index utility together with position-relative, position-absolute, position-fixed or position-sticky. The numeric utilities are intended for local stacking inside a component. Semantic utilities place application-specific elements on the same shared layers as library components.
<div class="position-relative z-index-1">Local layer</div>Class and token reference
| Class | Value |
|---|---|
.z-index-n1 | -1 |
.z-index-0 through .z-index-3 | 0 through 3 |
The semantic utilities follow the library’s stacking scale:
| Utility | Default | Intended layer |
|---|---|---|
z-index-header |
1000 | Sticky application headers |
z-index-tooltip |
1010 | Tooltips and menus |
z-index-overlay |
1040 | Modal and drawer backdrops |
z-index-drawer |
1050 | Drawers and modal dialogs |
z-index-toast |
1060 | Toast notifications |
<header class="position-sticky inset-block-start-0 z-index-header">...</header>Prefer the component’s built-in layer for library components. Use these utilities for custom elements that must deliberately participate in the same global stacking system. Each class and its matching --z-index-* custom property are generated from zIndexLevels in the Sass theme, so theme overrides keep both surfaces aligned.
Responsive behavior
Z-index utilities have no breakpoint variants. Their order applies within the current stacking context; a larger number cannot escape an ancestor stacking context. Use Positioning for responsive offsets while keeping layers consistent.
Recipes
Overlap local panels
Use z-index-n1, z-index-0, z-index-1, z-index-2 or z-index-3 for small stacking adjustments within the same component.
<div class="position-relative z-index-1">Lower layer</div>
<div class="position-relative z-index-2">Higher layer</div>Share the application header layer
Use the semantic class so custom sticky content follows the same theme token as the application header. Keep enough space for the header so it does not obscure focused controls.
<header class="position-sticky inset-block-start-0 z-index-header bg-surface">
Project navigation
</header>