atom

Tooltip

Displays informative text when users hover over, focus on, or tap an element.

Overview

The Tooltip component displays supplementary information when users hover over or focus on an element. It's commonly used to provide labels for icon-only buttons, explain disabled states, or offer additional context without cluttering the UI. Tooltips render via React Portals to document.body for proper z-stacking and viewport boundary handling. 

import { Tooltip, Button, IconButton } from '@enara-health/ui-react';
import { Settings, HelpCircle } from 'lucide-react';

<Tooltip title="This is a tooltip">
  <Button label="Hover me" />
</Tooltip>

<Tooltip title="Settings">
  <IconButton icon={<Settings />} aria-label="Settings" />
</Tooltip>

<Tooltip title="More information">
  <span style={{ cursor: 'help' }}>
    <HelpCircle size={20} />
  </span>
</Tooltip>

Props

Prop Type Default Description
title ReactNode - Required. Content displayed in the tooltip
children ReactElement - Required. Trigger element that activates the tooltip
placement TooltipPlacement 'top' Position of the tooltip relative to trigger
arrow boolean false Show arrow pointer
enterDelay number 100 Delay in ms before showing tooltip
leaveDelay number 0 Delay in ms before hiding tooltip
open boolean - Controlled open state
onOpen (event) => void - Callback when tooltip opens
onClose (event) => void - Callback when tooltip closes
disableHoverListener boolean false Disable hover trigger
disableFocusListener boolean false Disable focus trigger
disableInteractive boolean false Close when mouse leaves trigger (don't keep open on tooltip hover)

TooltipPlacement

The tooltip supports 12 placement positions:

'top-start' 'top' 'top-end' 'left-start' 'left' 'left-end' 'right-start' 'right' 'right-end' 'bottom-start' 'bottom' 'bottom-end'

Variants

With Arrow

Add an arrow pointer for a visual connection to the trigger element.

 
<Tooltip title="Tooltip with arrow" arrow>
  <Button label="With arrow" variant="secondary" />
</Tooltip>

<Tooltip title="Info tooltip" arrow>
  <IconButton icon={<Info />} aria-label="Info" />
</Tooltip>

Placements - Top

Position the tooltip above the trigger element.

 
<Tooltip title="Top start" placement="top-start" arrow>...</Tooltip>
<Tooltip title="Top (default)" placement="top" arrow>...</Tooltip>
<Tooltip title="Top end" placement="top-end" arrow>...</Tooltip>

Placements - Bottom

Position the tooltip below the trigger element.

 
<Tooltip title="Bottom start" placement="bottom-start" arrow>...</Tooltip>
<Tooltip title="Bottom" placement="bottom" arrow>...</Tooltip>
<Tooltip title="Bottom end" placement="bottom-end" arrow>...</Tooltip>

Placements - Left & Right

Position the tooltip to the side of the trigger element.

 
<Tooltip title="Left tooltip" placement="left" arrow>...</Tooltip>
<Tooltip title="Right tooltip" placement="right" arrow>...</Tooltip>

Custom Delays

Adjust enter and leave delays for different interaction patterns.

 
<Tooltip title="Fast" enterDelay={0}>...</Tooltip>
<Tooltip title="Normal" enterDelay={100}>...</Tooltip>
<Tooltip title="Slow" enterDelay={500}>...</Tooltip>

Examples

Icon Button Labels

Provide accessible labels for icon-only buttons.

 
<Tooltip title="Edit item" arrow>
  <IconButton icon={<Edit />} aria-label="Edit" />
</Tooltip>

<Tooltip title="Delete item" arrow>
  <IconButton icon={<Trash />} aria-label="Delete" color="danger" />
</Tooltip>

Help Text

Provide contextual help for form fields or UI elements.

Email address
 
<label>
  Email address
  <Tooltip title="We'll never share your email" arrow>
    <span style={{ cursor: 'help' }}>
      <HelpCircle size={14} />
    </span>
  </Tooltip>
</label>

Disabled Element Explanation

Explain why an element is disabled.

<Tooltip title="You need admin permissions to delete" arrow>
  <span>
    <Button label="Delete" disabled />
  </span>
</Tooltip>

Accessibility

  • Role: Tooltip element has role="tooltip".
  • ARIA Linking: Trigger element receives aria-describedby pointing to the tooltip when visible.
  • Keyboard Support: Tooltip appears on focus and disappears on blur, making it accessible via keyboard navigation.
  • Focus Management: Tooltip does not steal focus; the trigger maintains focus.
  • Reduced Motion: Respects prefers-reduced-motion by disabling animations.
  • WCAG Compliance: Meets AA standards for informational tooltips.

Best Practices

  • Keep tooltip content brief and concise
  • Don't put essential information only in tooltips - they're hidden by default
  • Use tooltips to supplement visible labels, not replace them
  • Avoid interactive content inside tooltips - use Popover instead
  • For icon-only buttons, always include aria-label on the button itself as a fallback
  • Consider mobile users - tooltips work on hover, which isn't available on touch devices
  • Don't repeat information that's already visible (e.g., button label)