Tooltip

Brief information shown on hover or focus.

When to use

Use a tooltip for short supplementary text on a trigger that already has an accessible name. Use a Popover when the content needs links, controls or a longer explanation.

Default

Use .tooltip with .tooltip-content so long text scrolls without clipping the arrow.

HTML
<div class="tooltip" role="tooltip">
	<div class="tooltip-content">Keep an unpublished copy of your changes.</div>
	<div class="tooltip-arrow top"></div>
</div>

Placements

Use .top, .right, .bottom or .left on .tooltip-arrow to match the tooltip’s physical position relative to its trigger. These placements stay physical in both LTR and RTL, so the arrow always points back toward the trigger. When positioning flips near a viewport edge, update the arrow class to the resolved placement.

HTML
<div class="tooltip" role="tooltip">
	<div class="tooltip-content">Tooltip top</div>
	<div class="tooltip-arrow top"></div>
</div>
<div class="tooltip" role="tooltip">
	<div class="tooltip-content">Tooltip bottom</div>
	<div class="tooltip-arrow bottom"></div>
</div>

Interactive

Use data-tooltip and data-tooltip-placement. While visible, aria-describedby links it to the trigger; hover or focus keeps it open, and Escape closes it without moving focus. The Showcase uses Floating UI for positioning tooltips. Floating UI flips or shifts the tooltip near viewport edges, tracks trigger movement and constrains long content so it scrolls inside the viewport.

The buttons below prefer top, right, bottom and left placement, respectively. They demonstrate tooltip behavior; connect their actions in your application.

HTML
<button
	class="btn btn-primary btn-solid"
	type="button"
	data-tooltip="Keep an unpublished copy of your changes."
	data-tooltip-placement="top">
	Save draft
</button>

<button
	class="btn btn-primary btn-solid"
	type="button"
	data-tooltip="Download this report as a CSV file."
	data-tooltip-placement="right">
	Export report
</button>

<button
	class="btn btn-primary btn-solid"
	type="button"
	data-tooltip="Copy this page's URL to the clipboard."
	data-tooltip-placement="bottom">
	Copy link
</button>

<button
	class="btn btn-primary btn-solid"
	type="button"
	data-tooltip="Invite teammates to review this project."
	data-tooltip-placement="left">
	Share project
</button>

Accessibility and behavior

  • Keep the trigger usable with keyboard and pointer input. While visible, connect the tooltip through aria-describedby; the tooltip does not replace the trigger name.
  • Keep it open while either the trigger or tooltip is hovered or the trigger is focused. Escape dismisses it without moving focus.
  • Do not put interactive controls in a tooltip. Essential instructions must remain available without hover; applications supply the positioning and dismissal behavior demonstrated by the Showcase.

CSS variables

Override these base defaults on the listed selector after the library styles. Variants and states may replace them; global tokens follow the active theme.

TokenDefaultPurposeScope / state
--tooltip-z-indexvar(--z-index-tooltip)Stacking order..tooltip
--tooltip-bg-colorvar(--bg-inverse)Background color..tooltip
--tooltip-colorvar(--text-inverse)Text and icon color..tooltip
--tooltip-padding-yvar(--spacer-1)Top and bottom padding..tooltip
--tooltip-padding-xvar(--spacer-2)Left and right padding..tooltip
--tooltip-border-radiusvar(--border-radius-sm, var(--border-radius))Corner radius..tooltip
--tooltip-font-sizevar(--font-size-xs, 0.75rem)Text size..tooltip
--tooltip-box-shadowvar(--shadow-lg)Outer shadow..tooltip
--tooltip-arrow-size0.375remBorder size used to draw the triangular arrow..tooltip