Tooltip

Tooltips are CSS-only overlays that appear on hover or keyboard focus. They use the data-tooltip attribute, no JavaScript required.

Basic usage

Hover over me

<span data-tooltip="This is a tooltip">Hover over me</span>

On interactive elements

<button class="button" data-tooltip="Save your changes">Save</button>

On buttons and links, the cursor remains pointer instead of the default help.

Positions

By default, tooltips appear above the element. Use data-tooltip-position to change placement.

Top Bottom Left Right

<span data-tooltip="Above (default)">Top</span>
<span data-tooltip="Below" data-tooltip-position="bottom">Bottom</span>
<span data-tooltip="To the left" data-tooltip-position="left">Left</span>
<span data-tooltip="To the right" data-tooltip-position="right">Right</span>

Accessibility

Tooltips appear on :hover and :focus-visible
Content is set via data-tooltip attribute and rendered with content: attr(data-tooltip), it is not accessible to screen readers
For critical information, do not rely on tooltips alone, add aria-label or visible text
Tooltips use pointer-events: none so they do not interfere with interaction

Usage rules

Do:

Use tooltips for supplementary, non-essential information
Keep tooltip text short (one sentence max)
Add aria-label when the tooltip contains essential context

Don't:

Don't put interactive content (links, buttons) in tooltips
Don't use tooltips for critical information that must be visible
Don't use tooltips on touch-only interfaces (they require hover)

CSS reference

This section documents how the component is built. For usage, see the sections above.

Styling

The tooltip defines no component tokens — values are set directly on the component rules, and dark mode is handled on the component rather than by token swaps.

Property	Value
Background	— dark mode:
Text colour	— dark mode:
Corner radius
Padding	`var(--space-xs) var(--space-s)`
Typography	, , , — pinned in full (with letter-spacing, case, style, and stretch normalised), because an unpinned pseudo-element inherits typography from its trigger: the same tooltip would render tighter on a button than on a span, and uppercase on a badge

Selectors

Selector	Purpose
`[data-tooltip]`	Base, sets relative positioning and `cursor: help`
`[data-tooltip]::before`	Tooltip bubble, positioned above, hidden by default; typography pinned so it never inherits from the trigger
`[data-tooltip]:hover::before`, `[data-tooltip]:focus-visible::before`	Shows tooltip on hover/focus
`[data-tooltip-position="bottom"]::before`	Bottom placement
`[data-tooltip-position="left"]::before`	Left placement
`[data-tooltip-position="right"]::before`	Right placement
`button[data-tooltip]`, `a[data-tooltip]`, `.button[data-tooltip]`	Overrides cursor to `pointer` for interactive elements

Use in another product

The design system installs once per product:

npm install github:bydefaultstudio/design-system-dist#semver:^4.7.0

This component's styles ship in design-system.css. No JavaScript, nothing else to include.