Skip to content
flyingsalmon

Icon tooltip

A focusable icon or emoji named by its tooltip text, so every standalone icon explains itself.

🍜

Installation

npx shadcn@latest add @flyingsalmon/icon-tooltip

Usage

import { Lock } from 'lucide-react'

import { IconTooltip } from '@/components/ui/icon-tooltip'

export function IconTooltipUsage() {
  return (
    <IconTooltip content="Locked, so the AI won’t change it">
      <Lock aria-hidden className="size-4" />
    </IconTooltip>
  )
}

Examples

On a card

The focus ring stands off the icon with a gap in the page colour. On a card, pass the matching offset through className, here focus-visible:ring-offset-card, so the gap takes the card’s colour.

Kyoto

Three days, two temples, one very long train ride.

Guidelines

When to use

  • To name a status icon that sits on its own: locked, tied to a date, a category.
  • For an icon inside a row or card whose whole surface is a link.

When not to use

  • Use Tooltip to label a button or any other control. The control is already focusable, so wrap it directly.
  • Use Badge for an icon beside text that already says the same thing. The icon is then decoration.

Do and don’t

  • Do
    Use it for a glyph that repeats across rows, such as a lock or an activity type, that would otherwise need a legend.The traveller learns the glyph once by pointing at it, and the page carries no key.
  • Do
    Keep status and category icons small and muted, grouped at the edge of the row with its other details.They are a quiet second read beside the content, not something to act on.
  • Don’t
    Make the icon the only place a reason lives. The row already says why a day is locked; the icon repeats it.Like any tooltip, it is out of reach on touch. It adds to what the page already says.

Accessibility

KeyDescription
TabMoves focus onto the icon, which opens the tooltip and draws the focus ring. Tabbing away closes it.
EscapeCloses the tooltip.
EnterSpaceDo nothing, because the icon has nothing to activate.

The icon is one Tab stop. It renders as role="img" with aria-label set to content, so a screen reader names it by the tooltip text whether or not the tooltip is open. A lucide icon inside is marked aria-hidden, so the name is not read twice. The pointer turns to the help cursor over it.

API

IconTooltip

PropTypeDefaultDescription
contentstringRequiredThe tooltip text and the icon’s accessible name.
childrenReactNodeRequiredThe icon or emoji. It is decorative, so mark a lucide icon aria-hidden; an emoji needs nothing. In a row whose surface is a link, place it beside the link, never inside: a focusable element nested in a link is invalid HTML.
classNamestring–Sizes the icon, such as [&>svg]:size-4, or sets the focus ring offset on another surface.

  • Tooltip

    The rules for tooltip content, and the label for a control.
  • Card

    An interactive card is one place the icon stays reachable.
  • Badge

    A visible status label when the icon is not enough.