Skip to main content

Layout

Z-index

The stacking scale — ten component layers from 100 to 300, the --z-* tokens, and why the top layer makes most of it moot.

The scale

Several Bootstrap components use z-index to layer navigation, tooltips, popovers and modals over the page. Stock Bootstrap counts from 1000 to 1090. rb-bootstrap re-maps the whole set onto the RopeBreak.net token scale — dropdown 100, modal 200, toast 300 — and slots Bootstrap's intermediate layers between those anchors.

Sass variableValueStock BootstrapRuntime variable
$zindex-dropdown1001000--bs-dropdown-zindex
$zindex-sticky1101020—
$zindex-fixed1201030—
$zindex-offcanvas-backdrop1901040—
$zindex-offcanvas1951045--bs-offcanvas-zindex
$zindex-modal-backdrop2001050--bs-backdrop-zindex
$zindex-modal2051055--bs-modal-zindex
$zindex-popover2101070--bs-popover-zindex
$zindex-tooltip2201080--bs-tooltip-zindex
$zindex-toast3001090--bs-toast-zindex

The order is the one that matters, not the numbers. Each layer is meant to be above the one before it: a dropdown inside a sticky header must beat the header, a modal must beat an offcanvas, a tooltip must show over a modal, and a toast must be visible over everything.

Do not customise these values individually. Change one and you likely need to change them all. Keep your own layers off the reserved numbers: anything from 1 to 99 is "in the page", anything you set at 100 or above is competing with a component.

Design tokens

The @ropebreak/design package defines four stacking tokens. The theme's compatibility layer re-emits them on :root, aliased onto the Sass scale above, so markup written against tokens.css keeps working.

TokenValueSource
--z-base0literal
--z-dropdown100$zindex-dropdown
--z-modal205$zindex-modal
--z-toast300$zindex-toast

Use the tokens in your own CSS when a custom element needs to sit on a component layer — a sticky "tale of the tape" strip, say — rather than inventing a number.

.tape-strip {
  position: sticky;
  top: 0;
  z-index: var(--z-dropdown); /* above content, below any menu */
}
Note the small mismatch: --z-modal resolves to 205 (the modal box), while the .z-modal utility below is 200 (the modal backdrop layer, which is the token's documented value). Both put you above an offcanvas and below a popover, so in practice they stack the same.

The top layer

Here is the twist. Because this theme has no JavaScript, most overlay components open through the Popover API or <dialog>. Elements shown that way render in the browser's top layer, a special stacking context that sits above every z-index in the document. Inside the top layer, order is simply the order in which things were opened — last one on top.

So the scale above only decides stacking for the parts that are still in normal flow:

ComponentUses z-index when…Ignores it when…
DropdownBuilt on <details>, or a static .show menuThe menu has the popover attribute
ModalOpened by the :target fallbackOpened by popovertarget or command="show-modal"
OffcanvasOpened by :target; the responsive .offcanvas-lg variant once it is in-flowOpened by popovertarget
PopoverNever — always a popover elementAlways
ToastA static .toast.show stackLive toasts with popover="manual"
TooltipAlways — rendered with pseudo-elements on the trigger—
Sticky / fixedAlways—

Two practical consequences:

  • A tooltip (220) cannot show over a popover-driven modal, because the modal is in the top layer and the tooltip is not. Put tooltips inside the modal's markup if you need them there — the pseudo-elements then belong to the top-layer subtree.
  • Open a toast, then a modal, and the modal covers the toast — top-layer order is chronological, not the 300 > 205 you might expect. Open the modal first and the toast lands on top.

Utilities

The z-index utilities expose a few document-level steps plus the three token anchors. They are !important, like every utility.

ClassValue
.z-n1-1
.z-00
.z-11
.z-22
.z-33
.z-dropdown100
.z-modal200
.z-toast300

.z-* only has an effect on positioned elements. Here three overlapping boxes are reordered with the small steps:

.z-3
.z-2
.z-1
.z-0
.z-n1
HTML
<div class="position-relative" style="height: 9rem">
  <div class="position-absolute top-0 start-0 z-3 border bg-body-tertiary p-3" style="width: 9rem">.z-3</div>
  <div class="position-absolute z-2 border bg-body-tertiary p-3" style="top: 1.5rem; left: 2.5rem; width: 9rem">.z-2</div>
  <div class="position-absolute z-1 border bg-body-tertiary p-3" style="top: 3rem; left: 5rem; width: 9rem">.z-1</div>
  <div class="position-absolute z-0 border bg-body-tertiary p-3" style="top: 4.5rem; left: 7.5rem; width: 9rem">.z-0</div>
  <div class="position-absolute z-n1 border bg-body-tertiary p-3" style="top: 6rem; left: 10rem; width: 9rem">.z-n1</div>
</div>

Sass

The scale lives in scss/_variables.scss, so a fork can shift it wholesale:

$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;

// Utility values (.z-*)
$zindex-levels: (
  n1: -1,
  0: 0,
  1: 1,
  2: 2,
  3: 3,
  dropdown: 100,
  modal: 200,
  toast: 300,
);