Z-index

VelinStyle uses a structured z-index token system to manage stacking contexts predictably. Utility classes and CSS custom properties keep layers organized.

Token System

All z-index values used internally by VelinStyle components are stored as CSS custom properties on :root. This prevents magic-number collisions and makes overriding straightforward.

:root {
  --velin-z-dropdown:   1000;
  --velin-z-sticky:     1020;
  --velin-z-fixed:      1030;
  --velin-z-drawer:     1040;
  --velin-z-modal-bg:   1050;
  --velin-z-modal:      1060;
  --velin-z-popover:    1070;
  --velin-z-tooltip:    1080;
  --velin-z-toast:      1090;
}

Utility Classes

Use .velin-z-{value} to apply z-index values from the utility scale.

Class          z-index value
────────────────────────────
.velin-z-n1    -1
.velin-z-0      0
.velin-z-1      1
.velin-z-2      2
.velin-z-3      3
.velin-z-auto   auto

<div class="velin-position-relative" style="height:100px">
  <span class="velin-position-absolute velin-z-3 velin-p-3 velin-bg-primary velin-text-white velin-rounded" style="top:0;left:0">z-3</span>
  <span class="velin-position-absolute velin-z-2 velin-p-3 velin-bg-info velin-text-white velin-rounded" style="top:10px;left:20px">z-2</span>
  <span class="velin-position-absolute velin-z-1 velin-p-3 velin-bg-warning velin-text-dark velin-rounded" style="top:20px;left:40px">z-1</span>
  <span class="velin-position-absolute velin-z-0 velin-p-3 velin-bg-light velin-rounded" style="top:30px;left:60px">z-0</span>
</div>

z-3 z-2 z-1 z-0

Component Stacking Order

VelinStyle components use the token variables internally so they always stack in a predictable order. The diagram below shows the layer hierarchy from bottom to top:

  ┌──────────────────────────────────────┐
  │  Toast          z-index: 1090       │  ← topmost
  │  Tooltip        z-index: 1080       │
  │  Popover        z-index: 1070       │
  │  Modal          z-index: 1060       │
  │  Modal backdrop z-index: 1050       │
  │  Drawer         z-index: 1040       │
  │  Fixed navbar   z-index: 1030       │
  │  Sticky header  z-index: 1020       │
  │  Dropdown       z-index: 1000       │
  │  Page content   z-index: auto       │  ← base
  └──────────────────────────────────────┘

Customizing

Override any token on :root to shift the entire stacking scale, or target a specific component.

:root {
  --velin-z-modal: 9999;   /* push modals above everything */
  --velin-z-toast: 10000;  /* keep toasts above the new modal level */
}