Utilities
Z-index
Use our low-level z-index utilities to quickly change the stack level of an element or component — on the theme's dropdown / modal / toast scale.
How it works
Use z-index utilities to stack elements on top of one another. Requires a
position value other than static, which can be set with custom styles or using
our position utilities.
We call these "low-level" z-index utilities because of their default values of
-1 through 3, which we use for the layout of overlapping components. High
z-index values are used for overlay components like modals, dropdowns and toasts. This theme
adds three named steps for those layers — .z-dropdown, .z-modal and
.z-toast — so you can put your own element on the same shelf as a component without guessing a
number. Stock Bootstrap has no named steps and uses 1000–1090 for its components.
HTML
<div class="position-relative" style="height: 160px">
<div class="z-3 position-absolute p-5 rounded-3 text-bg-cream border" style="left: 0">
<span class="fw-bold">z-3</span>
</div>
<div class="z-2 position-absolute p-5 rounded-3 text-bg-gold border" style="left: 2.5rem; top: 1rem">
<span class="fw-bold">z-2</span>
</div>
<div class="z-1 position-absolute p-5 rounded-3 text-bg-navy border" style="left: 5rem; top: 2rem">
<span class="fw-bold">z-1</span>
</div>
<div class="z-0 position-absolute p-5 rounded-3 bg-body-tertiary border" style="left: 7.5rem; top: 3rem">
<span class="fw-bold">z-0</span>
</div>
<div class="z-n1 position-absolute p-5 rounded-3 text-bg-light border" style="left: 10rem; top: 4rem">
<span class="fw-bold">z-n1</span>
</div>
</div>
.z-n1 sits behind the page content, which is why its card is hidden under the preview's
background unless the parent creates a stacking context.
The scale
| Class | z-index | Token | Meaning |
|---|---|---|---|
.z-n1 | -1 | — | Behind the parent's content (decorative backgrounds) |
.z-0 | 0 | --z-base | Reset |
.z-1 | 1 | — | Overlapping layout, lowest |
.z-2 | 2 | — | Overlapping layout |
.z-3 | 3 | — | Overlapping layout, highest |
.z-dropdown | 100 | --z-dropdown | Menus and anything that must clear sticky/fixed chrome (110/120) |
.z-modal | 200 | --z-modal | Dialog backdrops and boxes |
.z-toast | 300 | --z-toast | Notifications, above everything |
Where components sit
The theme's component layers are slotted between the three named steps. Knowing them tells you which utility to pick when your own fixed element has to clear one.
| Layer | Sass variable | Value |
|---|---|---|
Dropdown menu (--bs-dropdown-zindex) | $zindex-dropdown | 100 |
.sticky-top / .sticky-bottom | $zindex-sticky | 110 |
.fixed-top / .fixed-bottom | $zindex-fixed | 120 |
| Offcanvas backdrop | $zindex-offcanvas-backdrop | 190 |
Offcanvas panel (--bs-offcanvas-zindex) | $zindex-offcanvas | 195 |
Modal backdrop (--bs-backdrop-zindex) | $zindex-modal-backdrop | 200 |
Modal box (--bs-modal-zindex) | $zindex-modal | 205 |
Popover (--bs-popover-zindex) | $zindex-popover | 210 |
Tooltip (--bs-tooltip-zindex) | $zindex-tooltip | 220 |
Toast (--bs-toast-zindex) | $zindex-toast | 300 |
z-index on the page. The values above matter for the :target fallbacks, for
sticky and fixed chrome, and for your own positioned elements. See
Layout: Z-index for the full stacking story.Clearing sticky chrome
A sticky header is at 110. A floating "back to top" or a chat tab that must sit over it needs
.z-dropdown (100) or higher — in practice .z-modal is the safe pick for a
fixed element that should clear sticky and fixed bars but stay under dialogs.
Match 1 — Opener, 8:42
Match 2 — Tag team, 11:05
Match 3 — Women's title, 9:30
Match 4 — Hardcore, 12:18
Match 5 — Semi-final, 14:55
Match 6 — Semi-final, 13:40
Match 7 — Intercontinental title, 17:02
Match 8 — Cage main event, 22:31
HTML
<div class="docs-scroll-demo position-relative">
<div class="position-sticky top-0 z-1 p-2 bg-body border-bottom border-primary border-2 fw-bold">Sticky results header (z-1 here, 110 via .sticky-top)</div>
<div class="p-3">
<p>Match 1 — Opener, 8:42</p><p>Match 2 — Tag team, 11:05</p><p>Match 3 — Women's title, 9:30</p>
<p>Match 4 — Hardcore, 12:18</p><p>Match 5 — Semi-final, 14:55</p><p>Match 6 — Semi-final, 13:40</p>
<p>Match 7 — Intercontinental title, 17:02</p><p class="mb-0">Match 8 — Cage main event, 22:31</p>
</div>
<a href="#example-with-chrome" class="btn btn-primary btn-sm position-absolute bottom-0 end-0 m-3 z-dropdown">Back to top</a>
</div>CSS
Sass variables
// scss/_variables.scss — the token scale (100 / 200 / 300) with
// Bootstrap's intermediate layers slotted between.
$zindex-dropdown: 100;
$zindex-sticky: 110;
$zindex-fixed: 120;
$zindex-offcanvas-backdrop: 190;
$zindex-offcanvas: 195;
$zindex-modal-backdrop: 200;
$zindex-modal: 205;
$zindex-popover: 210;
$zindex-tooltip: 220;
$zindex-toast: 300;
$zindex-levels: (
n1: -1,
0: 0,
1: 1,
2: 2,
3: 3,
dropdown: 100,
modal: 200,
toast: 300,
);
CSS variables
The token layer re-emits the three named steps for CSS written against @ropebreak/design:
:root, [data-bs-theme="light"] {
--z-base: 0;
--z-dropdown: 100;
--z-modal: 200;
--z-toast: 300;
}
Utilities API
"z-index": (
property: z-index,
class: z,
values: $zindex-levels,
),