Tooltip

Overview

Add data-tip="Your tooltip text" to any element. The tooltip appears on hover via CSS ::before and ::after pseudo-elements. No JS, no wrapper elements. The element must be position:relative — add cursor:help for info tooltips or cursor:pointer for action tooltips.

Positions

<!-- Top (default) -->
<button data-tip="Tooltip text appears above">Hover me</button>

<!-- Bottom -->
<button data-tip-bottom data-tip="Tooltip text appears below">Hover me</button>

<!-- Left -->
<button data-tip-left data-tip="Tooltip text appears left">Hover me</button>

<!-- Right -->
<button data-tip-right data-tip="Tooltip text appears right">Hover me</button>

Common Use Cases

Location Status

Token Reference

Property	Value
Background	#0F172A (--sidebar-bg)
Text color	#fff
Font size	11px, fw-500
Padding	6px 10px
Border radius	7px (--r-xs + 1px)
Max width	220px (wraps long text)
Offset from element	8px gap
Arrow size	5px border triangle
Animation	opacity 0→1, 0.15s ease
z-index	9999 (always on top)

AI Implementation Notes

For AI coding assistants: Tooltips are purely CSS — no JavaScript needed. Add data-tip="text" to any element. The element must have position:relative (or be a block/inline-block element). For bottom position add the boolean attribute data-tip-bottom in addition to data-tip. Tooltip text must be plain text only — no HTML inside data-tip. For long tooltip text, the max-width:220px rule will wrap it automatically.

When to Use

Use Tooltip when

Explaining icon-only buttons (aria complement)
Showing additional context for truncated text
Providing keyboard shortcut hints
Explaining technical terms inline

Don't use Tooltip when

Critical information users must see — use hint text or alert
Long explanations (>2 sentences) — use a popover
On mobile — tooltips require hover, unavailable on touch

Properties

Property	Type	Required	Default	Description
data-tip	string	required	—	Tooltip text. Plain text only. Max 220px width with automatic wrapping.
position	attribute	optional	top	Add positional attribute for other directions. data-tip (top) \| data-tip-bottom \| data-tip-left \| data-tip-right

Design Decisions

Why pure CSS instead of JavaScript?

CSS-only tooltips via data-tip attribute require zero JavaScript, zero DOM manipulation, and zero event listeners. They work instantly, have no bundle cost, and degrade gracefully. The tradeoff is no smart positioning — tooltips can be clipped at viewport edges. For simple contextual hints, this tradeoff is acceptable.

Changelog

v1.0.0July 2026Added

Pure CSS implementation via data-tip attribute
4 positions: top, bottom, left, right
0.15s fade-in opacity transition

States

Tooltips have two states: hidden (default, opacity:0, pointer-events:none) and visible (on :hover of parent, opacity:1). Transition: opacity 0.15s ease. No other states apply.

Accessibility

Requirement	Implementation
aria-label supplement	Tooltips are visible supplements — never the sole source of information. Icon-only buttons must have aria-label even if they have a tooltip.
Touch devices	CSS :hover tooltips do not work on touch devices. Ensure all tooltip content is also accessible without hover.
Screen readers	Tooltip content (via data-tip) is NOT read by screen readers — it is a CSS pseudo-element. Use aria-label or title for assistive technology.

Composition

Allowed

On icon-only buttons (supplements aria-label)

On truncated text to show full content

On info SVG icons next to labels

Forbidden

On mobile — hover not available on touch

For critical information users must act on

With HTML content inside data-tip

Best Practices

Use tooltips to supplement information, never as the only way to convey it.

Tooltips are invisible until hover — critical info must be visible by default.

Don't

Rely on tooltip text as the aria-label replacement for icon buttons.

aria-label must be on the element itself — tooltips are CSS-only and not announced by screen readers.

Anatomy

Trigger Element

Any element with data-tip attribute. Must be position:relative (or block/inline-block). cursor:help for informational tooltips.

Tooltip Body (::after)

CSS pseudo-element. bg:#0F172A, color:#fff, 11px fw-500, padding:6px 10px, radius:7px, max-width:220px. Offset 8px from element.

Arrow (::before)

CSS border triangle (5px). Color matches tooltip bg. Positioned between element and tooltip body.

Content Rules

Good tooltip text

Export all data as CSV file

Plain text, brief, explains what happens

Bad tooltip text

Click this button to begin the process of exporting your data...

Too long. Tooltips should be 1 short sentence max.

Behavior

Tooltips are CSS-only — no JavaScript involved. They appear on :hover of the parent element via ::after pseudo-element with opacity:0 → opacity:1 at 0.15s ease. They disappear immediately when hover ends. Position is fixed relative to the trigger element — they do not reposition to avoid viewport edges. On touch devices, tooltips are not accessible (no hover). Always ensure the information in the tooltip is also accessible through another means on touch.