Z-index and layering
Place menus, overlays, and composed surfaces on predictable layers with named z-index tokens.
Z-index scale
Named z-index tokens make the order between independent layers explicit. Keep each local stacking context small. Prefer a component such as Modal or Dropdown Menu before assigning an application-owned layer yourself.
hideDecorative content behind the base plane.
baseDefault document content.
dockedPersistent rails and pinned UI.
dropdownMenus, selects, and command panels.
stickyScroll-aware headers and controls.
overlayTransient backdrops and scrims.
modalFocused dialogs and blocking decisions.
popoverAnchored contextual surfaces.
tooltipHighest-priority hints and explanations.
maxReserved maximum layer for exceptional integrations.
Layer a custom surface
A z-index token orders an element within its current stacking context. It cannot move above a parent stacking context, so place custom overlays deliberately and avoid escalating numeric values.
base
0
dropdown
1000
tooltip
1800
import { Box, Text } from "@smoothie-framework/whisk-react";
<Box position="relative" minHeight={52} padding={4} background="surface2" rounded="xl" border="sm" borderColor="borderSubtle" overflow="hidden" isolation="isolate">
<Box position="absolute" zIndex="base" top="1rem" left="1rem" width={28} padding={3} background="surface1" rounded="lg" border="sm" borderColor="border">
<Text textStyle="body" weight="semibold">base</Text>
<Text textStyle="body" color="subtle">0</Text>
</Box>
<Box position="absolute" zIndex="dropdown" top="4.25rem" left="4.5rem" width={28} padding={3} background="warningMuted" rounded="lg" border="sm" borderColor="borderStrong">
<Text textStyle="body" weight="semibold">dropdown</Text>
<Text textStyle="body" color="subtle">1000</Text>
</Box>
<Box position="absolute" zIndex="tooltip" top="8rem" left="8rem" width={28} padding={3} background="accentSubtle" rounded="lg" border="sm" borderColor="borderFocus">
<Text textStyle="body" weight="semibold" color="textInverse">tooltip</Text>
<Text textStyle="body" color="textInverse">1800</Text>
</Box>
</Box>