Skip to content
Browse documentation
whisk/ui

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.

hide

Decorative content behind the base plane.

base

Default document content.

docked

Persistent rails and pinned UI.

dropdown

Menus, selects, and command panels.

sticky

Scroll-aware headers and controls.

overlay

Transient backdrops and scrims.

modal

Focused dialogs and blocking decisions.

popover

Anchored contextual surfaces.

tooltip

Highest-priority hints and explanations.

max

Reserved 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>

Z-index props

PropTypeDefaultDescription
zIndexZIndexTokenbasePlace a positioned element on the shared layer scale.
positionResponsiveUtilitystaticUse a positioned element for predictable custom overlays and layers.