Skip to content
flyingsalmon

Tooltip

A short text label anchored to its trigger that never takes focus.

Installation

npx shadcn@latest add @flyingsalmon/tooltip

Usage

import { Share2 } from 'lucide-react'

import { Button, ButtonSize, ButtonVariant } from '@/components/ui/button'
import { Tooltip } from '@/components/ui/tooltip'

export function TooltipUsage() {
  return (
    <Tooltip content="Share the trip">
      <Button
        variant={ButtonVariant.Outline}
        size={ButtonSize.Icon}
        aria-label="Share the trip"
        icon={<Share2 />}
      />
    </Tooltip>
  )
}

Examples

Placement

side picks the edge and align lines the tooltip up along it. A tooltip that would leave the viewport flips to the other side.

A keyboard shortcut

Type the shortcut into the string. The tooltip is the one place a shortcut belongs, and the label stays plain text.

Any focusable child

A tooltip wraps any single element, not only a Button, as long as the element is focusable. An Avatar takes no focus of its own, so this one adds tabIndex at the call site.

BN

Guidelines

When to use

  • To name an icon-only control: "Add a place", "Share the trip".
  • To add a keyboard shortcut to a label.
  • To clarify something with one short sentence that the page can do without.

When not to use

  • Use Icon tooltip for an icon that only explains itself and is not a control. Icon tooltip makes it focusable and names it.
  • Use Alert for a reason, a result, or an error. These must be seen, so they go on the page next to what they describe.
  • Use Dialog for content with links, buttons, or images. A tooltip closes when the pointer leaves, so nothing inside it can be used.

Do and don’t

  • Do
    Keep it to one or two sentences the traveller does not need in order to act. If they must read it, put it on the page.A tooltip is out of reach on touch, and a screen reader that never focuses the trigger never hears it.
  • Don’t
    Hide why a control is disabled in a tooltip. Write the reason next to the control.A disabled control cannot open a tooltip, and the reason is the one thing the traveller needs to move on.
  • Don’t
    Put a tooltip on every row.A few explained terms on a screen stand out. One on every row is noise nobody hovers.

Accessibility

KeyDescription
TabMoves focus onto the trigger, which opens the tooltip. Tabbing away closes it.
EscapeCloses the tooltip. Inside a dialog, it closes the tooltip before the dialog.

The tooltip never takes focus and draws no ring of its own; the trigger keeps whichever ring it already has. The pointer can cross the gap from the trigger onto the tooltip without closing it, and any pointer press closes it.

The tooltip sets aria-describedby on the trigger and renders a node with role="tooltip", so the trigger keeps its own name and the tooltip only describes it. An icon-only button therefore needs an aria-label of its own.

A disabled button fires no pointer or focus events, so a tooltip on it never opens. An element that cannot take focus never shows its tooltip to a keyboard traveller.

API

Tooltip

PropTypeDefaultDescription
contentstringRequiredThe label. Text only.
childrenReactElementRequiredOne focusable element that anchors the tooltip. The component adds no tabIndex, so give a text span tabIndex={0}. An icon-only button keeps its own aria-label as well.
sideTooltipSideTooltipSide.TopWhich edge of the trigger the tooltip opens from. It flips when there is no room.
alignTooltipAlignTooltipAlign.CenterHow the tooltip lines up along that edge.
openboolean–The controlled open state.
defaultOpenbooleanfalseThe initial open state when uncontrolled.
onOpenChange(open: boolean) => void–Called when the tooltip opens or closes.

TooltipProvider

Mount it once at the app root. It fixes the open delay for every tooltip.

PropTypeDefaultDescription
childrenReactNodeRequiredThe app.

  • Icon tooltip

    A focusable icon named by its own tooltip.
  • Button

    The usual trigger, with an aria-label when icon-only.
  • Avatar group

    Names each traveller with a tooltip.
  • Accessibility

    Focus, keyboard, and contrast rules for every component.