z-index Best Practices for Tooltips

Tooltip z-index Strategy

Tooltips should appear above virtually everything else on the page. They are brief, contextual, and must never be clipped or hidden by other UI layers. This requires the highest z-index value in your scale.

Position in the z-index Hierarchy

:root {
  --z-dropdown: 1000;
  --z-sticky: 1020;
  --z-overlay: 1040;
  --z-modal: 1050;
  --z-popover: 1060;
  --z-toast: 1080;
  --z-tooltip: 1090; /* highest layer */
}

Basic Tooltip Implementation

.tooltip {
  position: absolute;
  z-index: var(--z-tooltip);
  background: #1a1a2e;
  color: #ffffff;
  padding: 0.5rem 0.75rem;
  border-radius: 6px;
  font-size: 0.8125rem;
  pointer-events: none;
  white-space: nowrap;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.2);
}

.tooltip::after {
  content: '';
  position: absolute;
  /* arrow/caret styling */
}

Portal-Based Tooltips

For tooltips to reliably appear above all content, render them as children of document.body:

// React example using a portal
function Tooltip({ children, content, targetRef }) {
  return createPortal(
    <div
      className="tooltip"
      style={{
        position: 'fixed',
        zIndex: 'var(--z-tooltip)',
        top: targetRef.current.getBoundingClientRect().bottom + 4,
        left: targetRef.current.getBoundingClientRect().left,
      }}
    >
      {content}
    </div>,
    document.body
  );
}

Tooltip Libraries and z-index

Popular tooltip libraries handle z-index internally:

Library	Default z-index	Configurable?
Tippy.js	9999	Yes, via zIndex prop
Floating UI	auto	Yes, via style
Radix Tooltip	(portal)	Yes, via CSS
MUI Tooltip	1500	Via theme

Key Considerations

1. Always use portals: Render tooltips at the body level to avoid stacking context traps
2. Use pointer-events: none: Tooltips should not block interaction with underlying elements
3. Consider touch devices: Tooltips triggered by hover may need a tap-to-show alternative
4. Tooltip over tooltip: If a tooltip can trigger another tooltip, ensure consistent z-index ordering
5. Accessibility: Use role="tooltip" and aria-describedby for screen readers