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.

HTML
<div class="position-relative z-index-1">Local layer</div>

Class and token reference

ClassValue
.z-index-n1-1
.z-index-0 through .z-index-30 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
HTML
<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.

z-index-1
z-index-2
HTML
<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.

HTML
<header class="position-sticky inset-block-start-0 z-index-header bg-surface">
	Project navigation
</header>