Skip to main content

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.

z-3
z-2
z-1
z-0
z-n1
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

Classz-indexTokenMeaning
.z-n1-1—Behind the parent's content (decorative backgrounds)
.z-00--z-baseReset
.z-11—Overlapping layout, lowest
.z-22—Overlapping layout
.z-33—Overlapping layout, highest
.z-dropdown100--z-dropdownMenus and anything that must clear sticky/fixed chrome (110/120)
.z-modal200--z-modalDialog backdrops and boxes
.z-toast300--z-toastNotifications, 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.

LayerSass variableValue
Dropdown menu (--bs-dropdown-zindex)$zindex-dropdown100
.sticky-top / .sticky-bottom$zindex-sticky110
.fixed-top / .fixed-bottom$zindex-fixed120
Offcanvas backdrop$zindex-offcanvas-backdrop190
Offcanvas panel (--bs-offcanvas-zindex)$zindex-offcanvas195
Modal backdrop (--bs-backdrop-zindex)$zindex-modal-backdrop200
Modal box (--bs-modal-zindex)$zindex-modal205
Popover (--bs-popover-zindex)$zindex-popover210
Tooltip (--bs-tooltip-zindex)$zindex-tooltip220
Toast (--bs-toast-zindex)$zindex-toast300
Most overlays in this theme — modal, offcanvas, popovers, toasts, enhanced dropdowns — open through the Popover API into the browser's top layer, which paints above every 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.

Sticky results header (z-1 here, 110 via .sticky-top)

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

Back to top
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,
),