Use tooltip for brief, optional clarification on icon buttons or abbreviated labels.
Tooltip
Short contextual hint shown near a trigger on hover or focus.
This field is required
- .source-tooltip-trigger Positioning wrapper around trigger
- .source-tooltip Floating tooltip surface
- [data-source-side] Placement side modifier
- [data-source-open] Visibility state
States
StateBehavior
HiddenDefault. Tooltip is invisible and removed from the accessibility tree.
VisibleShown after hover delay or on focus.
data-source-open="true" triggers the fade in.Design intent
Tooltip surfaces supplementary information that helps but is not required to complete the task. It is purely additive — the UI must work without it. When the information is important enough that most users need it to proceed, put it inline instead.
When to use
Do
Keep tooltip text under 10 words — it should answer a quick question, not explain a feature.
Pair icon-only buttons with a tooltip that restates the action label.
Don't
Do not put required instructions inside a tooltip — touch users cannot access them.
Do not put interactive elements (links, buttons) inside the tooltip content.
Avoid tooltips on text that is already self-explanatory.
Designer checklist
- Trigger has a visible label or icon that communicates purpose without the tooltip.
- Tooltip text is under 10 words.
- Tooltip content is not required to complete the task. Critical info is surfaced inline.
- Touch users can access the same information through an alternative path.
Tooltip props
PropTypeDefaultDescription
contentReactNoderequiredTooltip content.
childrenReactElementrequiredSingle trigger element.
sidetop | right | bottom | lefttopPreferred placement side.
delayShownumber120Delay in ms before showing.
delayHidenumber0Delay in ms before hiding.
Basic usage
import { Tooltip } from '@pierredelattre/source-react';
<Tooltip content="Save your changes">
<Button variant="ghost" ariaLabel="Save" leadingIcon={<SaveIcon />} />
</Tooltip>Placement
<Tooltip content="Copied!" side="right">
<button>Copy</button>
</Tooltip>
<Tooltip content="Deletes all records" side="bottom" delayShow={300}>
<Button intent="danger">Clear all</Button>
</Tooltip>Component tokens
TokenDefault
--source-tooltip-bg--source-color-text
--source-tooltip-color--source-color-text-inverse
--source-tooltip-radius--source-radius-md
--source-tooltip-font-size0.75rem
ARIA attributes
AttributePurpose
role="tooltip"Identifies contextual helper text for assistive technology.
aria-describedbyConnects trigger to tooltip content so screen readers announce it.
Keyboard support
KeyBehavior
TabFocuses the trigger and shows the tooltip.
EscapeDismisses the tooltip while keeping focus on the trigger.
Touch considerations
Hover-based tooltips are not accessible on touch devices. Any information inside a tooltip must also be reachable through an alternative — inline hint text, a label, or a separate screen.