Tooltip HTML/CSS

Tooltips: contextual hints done right

A tooltip is a small, passive UI element that surfaces extra context when the user hovers over or focuses an interactive element. Think of it as a footnote attached to a button or icon — useful for clarifying a label, defining a term, or explaining what a tiny icon does. Tooltips are passive: they only display information and never contain interactive controls. The moment you need a link or a button inside, you have outgrown the tooltip and should reach for a popover or a modal.

The simplest tooltip is the native title attribute: <button title="Save changes">💾</button>. Zero JavaScript, zero CSS, supported everywhere — but you cannot style it, it never appears on mobile (no hover), and it is half-broken for keyboard users. For anything beyond a developer prototype, you need a custom implementation.

Accessibility basics

A real tooltip requires role="tooltip" on the bubble plus aria-describedby on the trigger pointing at the tooltip id. Use describedby, not aria-label: the latter replaces the accessible name and would hide the visible label from screen readers. The tooltip must also open on keyboard focus, not only on mouse hover, or your form fields become unusable with a screen reader.

<button aria-describedby="tip1">?</button>
<span role="tooltip" id="tip1">Required field</span>

WCAG 2.1 success criterion 1.4.13 (Content on Hover or Focus) demands three properties: dismissible (Esc closes the tooltip without moving the pointer), hoverable (the user can move the cursor onto the bubble without it disappearing) and persistent (it stays until dismissed or the trigger loses focus).

Popular libraries

• Tippy.js (by Atomiks) — tiny wrapper over Popper, great defaults, themable.
• Floating UI — the modern rebrand of Popper.js, headless positioning toolkit with auto-flip and collision detection.
• Radix Tooltip and @headlessui/react — accessible primitives shipped with shadcn/ui and Tailwind UI.
• MUI Tooltip and Ant Design Tooltip — opinionated, themed components for design systems.
• react-tooltip — simple drop-in for React apps that do not need a full design system.

Positioning and timing

Default to top placement with an auto-flip when the bubble would clip the viewport — Floating UI handles this with its flip() middleware. Use a 300–500 ms open delay to avoid flicker as the cursor brushes elements; close immediately to feel responsive. Animations should be subtle: a 120 ms fade plus a 4 px slide. Tooltips on touch devices need a different strategy entirely — there is no hover, so map them to long-press or convert to an inline popover.

Anti-patterns

• Critical information hidden in a tooltip — invisible by default, fails on mobile, fails WCAG.
• Long paragraphs inside a tooltip — use a popover or an inline help section.
• Tooltips containing links or buttons — users cannot reliably move into them; promote to a popover.
• Pure-CSS :hover tooltips without focus support — unusable by keyboard.

FAQ

Is the title attribute enough? Only for quick prototypes. It is not stylable, not visible on touch devices and screen-reader support is inconsistent. For production, use a real tooltip component.

When should I use a popover instead? The moment the bubble needs interactive content — links, buttons, form fields — switch to a popover. Tooltips are read-only.

aria-describedby or aria-label? aria-describedby. A label replaces the accessible name; a description augments it, which is what a tooltip really is.

What about the new Popover API? The native popover attribute (Chrome 114+, Firefox 125+) is great for popovers but is not a tooltip primitive — it does not handle aria-describedby wiring automatically. Combine it with Floating UI or stick with Tippy for now.