Z-Index Management

Layering systems control interface stacking — layering should remain intentional and predictable.

01 — Purpose

Intentional stacking order

Layering systems control interface stacking behaviour — layering should remain intentional and predictable.

Overlays, navigation, tooltips, and toasts all compete for the same visual plane. Without a documented scale, teams bump z-index values until nothing can be reasoned about — the classic escalation war.

See cascade layers for precedence in the cascade itself, and patterns like modal dialog and popovers for overlay behaviour.

02 — Principles

Predictable layering

Layering systems should reduce chaos — not create it.

  • documented layering scale — every level has a name and purpose
  • restrained z-index usage — only where stacking context is required
  • logical overlay hierarchy — lower layers never accidentally cover higher-priority UI

03 — Practice

Common layers and good practice

Navigation, popovers, dialogs, and notifications — each belongs on a defined tier.

  • define tokens or variables for each tier — e.g. --layer-nav, --layer-popover, --layer-dialog
  • navigation sits below modals — menus should not cover an open dialog
  • popovers and dropdowns share a tier — consistent above page content, below modals
  • dialogs and focus traps above page chrome — see modal dialog
  • notifications and toasts at the top — visible without blocking primary interaction

04 — Avoid

Z-index escalation

Random high values make every new overlay a guessing game.

  • random high values — z-index: 99999 to “fix” one bug
  • z-index escalation wars — each PR adds another arbitrary number
  • undocumented layering systems — no shared reference for new components
  • stacking context surprises — transforms and filters creating unexpected isolation
  • mixing z-index with !important — see cascade layers for better override strategy

05 — Close

Document the stack once

A small named scale beats an infinite numeric arms race.

Add a layering section to your design tokens or CSS architecture doc. When a new overlay ships, assign it to an existing tier — do not invent a new number.

See design tokens, CSS architecture, and toast notifications.