The tooltip is a compact label for short hints. The hover card is a portal panel for rich previews — avatars, bios, stats. Use tooltips for one line; hover cards when the user needs more context.
Tooltip vs hover card
Need
Component
Content size
Icon-only button label
Tooltip
One short phrase
Keyboard shortcut hint
Tooltip
Text + optional prefix icon
User profile preview
Hover card
Avatar, name, tags, links
Feature explanation
Hover card
Multi-line description
The tooltip renders as a small Row with role tooltip. The hover card wraps the animation primitive with hover trigger type and portals content above or beside the trigger.
Tooltip basics
The tooltip accepts a label and optional prefixIcon or suffixIcon. It is a presentational shell — pair it with a parent that handles show/hide positioning (for example an IconButton wrapper or a focusable trigger).
Row vertical="center" gap="4"
IconButton icon="info" variant="ghost" aria-label="More info"
Tooltip label="Exports include all filtered rows" prefixIcon="info"
Keep labels under ~60 characters. If the explanation needs a paragraph, use a hover card instead.
When not to use tooltips
Mobile-only flows (no hover) — use visible helper Text or a Dialog
Critical instructions the user must read — put them inline
Interactive content (links, buttons) inside the hint — use a hover card
Hover card for rich previews
The hover card takes a trigger element and children for the floating panel. Defaults: fade + slight slide-up, portal rendering, placement top.Typical profile preview structure inside the card:
Column padding="16" gap="12" radius="l" background="page" border="neutral-alpha-weak" maxWidth={24}
Row gap="12" vertical="center"
Avatar size="l"
Column gap="4"
Heading variant="heading-strong-s" → name
Text variant="body-default-s" → role
Text variant="body-default-s" → short bio
Row gap="8" wrap
Tag → skill labels
Set tabIndex=0 on non-focusable triggers (Avatar, Icon) so keyboard users can reach the card. The animation layer shows the panel on hover and focus.
Placement and motion
Override placement (top, bottom, start, end) when the trigger sits near viewport edges. Tune duration or scale sparingly — defaults are tuned for UI density.
Density guidelines
Surface
Recommendation
Data table column header
Tooltip on info icon
Avatar in comment thread
Hover card with name + role
Chart data point
Tooltip with value label
Pricing feature list
Inline Text, not hover-only
Never hide required information exclusively behind hover. Tooltips and cards supplement visible UI; they do not replace it.
Write this / not this
✅ Once UI way
❌ Common mistake
Tooltip for one-line hints
Paragraph text in a tooltip
Hover card for multi-field previews
Stacking 5 tooltips on one icon
tabIndex on hover triggers
Hover-only with no keyboard path
Visible labels on icon buttons
Tooltip as the only accessible name
Check yourself
Icon buttons have aria-label even when a tooltip exists
Hover card content fits without horizontal scroll (maxWidth)
Critical info is visible without hovering
Triggers near screen edges use adjusted placement
Tag rows in previews use the Tag component, not raw spans
