Z-index

Overview

Several Chassis CSS components rely on z-index to control how elements layer on top of one another. Two separate scales handle this: a high-value stack (1000–1090) for full-page overlay components such as menus, modals, and tooltips; and a low-value set (1–3) for border control within compact components such as button groups and input groups.

Component scale

The component z-index stack assigns an explicit value to each overlay tier so that layering between components is predictable and conflict-free. Values begin at 1000 and increment in steps large enough to accommodate future tiers without renumbering the existing scale.

The exact starting value is arbitrary — any sufficiently high baseline would work — but the relative ordering matters. Avoid changing individual values in isolation; the stack depends on ordered increments, so adjusting one value typically requires adjusting all values above it.

Border overlap

For components where adjacent borders need to stack — button groups and input groups, for example — Chassis CSS uses low single-digit z-index values to bring the interactive element to the foreground: 1 for hover, 2 for active, and 3 for focus. This ensures the focused or activated element's border renders over adjacent siblings without additional overrides.

Utility classes

The $zindex-levels map generates .z-{n} utility classes for any positioned element. Values range from .z-n1 (z-index: -1) through .z-5 (z-index: 5). These classes have no effect on elements with position: static.

See Z-index utilities for the full class reference.

CSS

The z-index system is defined entirely through Sass variables and maps — no CSS custom properties are involved.

Sass variables

$zindex-menu through $zindex-toast define the component overlay stack. Adjust them before importing Chassis to shift individual tiers, keeping in mind that the stack depends on ordered increments.

$zindex-menu:                       1000;
$zindex-sticky:                     1020;
$zindex-fixed:                      1030;
$zindex-drawer:                     1040;
$zindex-modal:                      1050;
$zindex-alert:                      1060;
$zindex-popover:                    1070;
$zindex-tooltip:                    1080;
$zindex-toast:                      1090;

Sass maps

$zindex-levels maps named keys (n1 through 5) to their integer values and drives the generated .z-* utility classes.

$zindex-levels: (
  n1: -1,
  0: 0,
  1: 1,
  2: 2,
  3: 3,
  4: 4,
  5: 5
);