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 variable | Value | Stock Bootstrap | Runtime variable |
|---|---|---|---|
$zindex-dropdown | 100 | 1000 | --bs-dropdown-zindex |
$zindex-sticky | 110 | 1020 | — |
$zindex-fixed | 120 | 1030 | — |
$zindex-offcanvas-backdrop | 190 | 1040 | — |
$zindex-offcanvas | 195 | 1045 | --bs-offcanvas-zindex |
$zindex-modal-backdrop | 200 | 1050 | --bs-backdrop-zindex |
$zindex-modal | 205 | 1055 | --bs-modal-zindex |
$zindex-popover | 210 | 1070 | --bs-popover-zindex |
$zindex-tooltip | 220 | 1080 | --bs-tooltip-zindex |
$zindex-toast | 300 | 1090 | --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.
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.
| Token | Value | Source |
|---|---|---|
--z-base | 0 | literal |
--z-dropdown | 100 | $zindex-dropdown |
--z-modal | 205 | $zindex-modal |
--z-toast | 300 | $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 */
}
--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:
| Component | Uses z-index when… | Ignores it when… |
|---|---|---|
| Dropdown | Built on <details>, or a static .show menu | The menu has the popover attribute |
| Modal | Opened by the :target fallback | Opened by popovertarget or command="show-modal" |
| Offcanvas | Opened by :target; the responsive .offcanvas-lg variant once it is in-flow | Opened by popovertarget |
| Popover | Never — always a popover element | Always |
| Toast | A static .toast.show stack | Live toasts with popover="manual" |
| Tooltip | Always — rendered with pseudo-elements on the trigger | — |
| Sticky / fixed | Always | — |
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.
| Class | Value |
|---|---|
.z-n1 | -1 |
.z-0 | 0 |
.z-1 | 1 |
.z-2 | 2 |
.z-3 | 3 |
.z-dropdown | 100 |
.z-modal | 200 |
.z-toast | 300 |
.z-* only has an effect on positioned elements. Here three overlapping boxes are reordered
with the small steps:
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,
);