Tooltip

A short supplementary label for a control, shown on hover and keyboard focus.

Essential information: put it in visible text.
An info icon that reveals details: use Popover (Wave 2).
Touch-first UI: tooltips do not open on touch.

Install

Terminal

pnpm dlx shadcn@latest add @acme/tooltip

Or import from the package: import { TooltipProvider } from '@acme/react'

Examples

Basic

tooltip-basic.tsx

import { Copy, Download, Share2 } from 'lucide-react'
import { IconButton } from '@/components/ui/icon-button'
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip'

const actions = [
  { label: 'Copy link', icon: Copy },
  { label: 'Download PDF', icon: Download },
  { label: 'Share', icon: Share2 },
]

export default function TooltipBasic() {
  return (
    <TooltipProvider>
      <div className="flex gap-1">
        {actions.map(({ label, icon: Icon }) => (
          <Tooltip key={label}>
            <TooltipTrigger
              render={
                <IconButton label={label} size="sm">
                  <Icon />
                </IconButton>
              }
            />
            <TooltipContent>{label}</TooltipContent>
          </Tooltip>
        ))}
      </div>
    </TooltipProvider>
  )
}

Native

The same component for iOS (SwiftUI, AcmeUI) and Android (Jetpack Compose, com.acme.ui), built on each platform's own controls with the same tokens.

.acmeTooltip

Swift

AcmeIconButton("Copy link", systemImage: "doc.on.doc") { copy() }
    .acmeTooltip("Copies a link anyone in your workspace can use")

Shows on pointer hover (iPad, Mac) and is read by VoiceOver as a hint. Touch has no hover, so never put essential information only here.

Tooltip on iOS, light mode — iOS, light mode

Tooltip on iOS, dark mode — iOS, dark mode

Props

Tooltip props
Prop	Type	Default	Description
TooltipProvider.delay	number	400	Hover delay before opening, in ms.
TooltipContent.side	'top' \| 'right' \| 'bottom' \| 'left'	'top'	Preferred side.
TooltipTrigger.render	ReactElement	—	Make an existing control the trigger: render={<IconButton label="Copy" />}.

Keyboard
Key	Action
`Tab (focus)`	Opens
`Escape`	Closes

Role: tooltip
You provide: The trigger has its own accessible name; the tooltip only repeats or supplements it.
Built in: Hoverable, dismissible and persistent (WCAG 1.4.13).
Uses foreground on background, the highest-contrast pair in every mode.
WCAG 2.2 criteria: 1.4.13, 2.1.1

Don’t

Put links or buttons inside a tooltip.
Use a tooltip as the only label for an icon button.

Tokens

color.foreground
color.background
radius.md
z.tooltip