Skip to content
Tutorials Center
My learning

Topics

Lesson 93 of 139 ยท UI Components

Tooltips

Build tooltips with ::after and attr(), add arrows, place them on any side, and make them accessible with aria-describedby, focus support and Escape to close.

A tooltip is a small label that pops up when you point at or focus something. It's the "Copy link" bubble above a share icon, or the short explanation next to a form field. Tooltips are useful for naming icon buttons and adding a hint without cluttering the layout.

They're also one of the most misused components on the web. Content that only appears on hover is invisible on touch screens, easy to miss, and hard to read for people who zoom in. In this lesson you will build a quick CSS-only tooltip, add arrows and positions, then build a properly accessible version and a tap-friendly "toggletip". Along the way you will learn the rules that decide when a tooltip is the right tool at all.

When to use a tooltip

A tooltip should hold short, supplementary information: a few words that help but aren't required. Good examples:

  • The name of an icon-only button ("Bold", "Download").
  • A keyboard shortcut ("Save (Ctrl+S)").
  • The full text of something that was truncated.

Bad examples:

  • Instructions people need to complete a form. Put them on the page, next to the field.
  • Error messages. They must stay visible.
  • Anything long, interactive, or containing links. That's a popover or a dialog, not a tooltip.

A simple test: if a mobile user can't hover, will they miss something important? If yes, it shouldn't be hover-only.

Avoid the title attribute for tooltips. The browser's built-in title tooltip appears after a long delay, can't be styled, never appears for keyboard or touch users, and is announced inconsistently by screen readers. It's fine as a bonus, but never rely on it for information people need.

A CSS-only tooltip with attr()

The quickest tooltip needs no extra elements. Put the text in a data attribute, and display it with a pseudo-element using content: attr(data-tip):

CSS
[data-tip] {
  position: relative;
}
[data-tip]::after {
  content: attr(data-tip);
  position: absolute;
  bottom: calc(100% + 8px);   /* above the element, with a gap */
  left: 50%;
  translate: -50% 0;          /* centered horizontally */
  /* ...colors, padding, radius... */
}

The two-step centering is a classic: left: 50% puts the tooltip's left edge at the middle of the trigger, then translate: -50% shifts it back by half its own width. Centering Anything explains why this works for elements of unknown width.

Adding an arrow

The arrow is a second pseudo-element, ::before. The oldest trick draws a triangle with borders: a box with zero width and height and thick borders shows four triangles meeting in the middle. Make three of them transparent and only one remains:

CSS
[data-tip]::before {
  content: "";
  border: 6px solid transparent;
  border-top-color: #1e293b;  /* a triangle pointing down */
}

A box with only a top border color shows a downward triangle, perfect for a tooltip above its trigger.

CSS-only tooltips with arrows

Some details worth copying:

  • width: max-content plus max-width. An absolutely positioned box inside a small button would otherwise shrink to the button's width and wrap every word. max-content lets short tips stay on one line; max-width makes long ones wrap neatly.
  • pointer-events: none stops the invisible tooltip from catching hovers meant for things beneath it. The User Interface Properties lesson covers this property.
  • :focus-visible shows the tip for keyboard users, not just mouse users.
  • The delayed visibility lets the fade-out finish before the tooltip is hidden, the same trick as in Dropdown Menus.

For left and right positions, use top: 50% with translate: 0 -50%, put the bubble at right: calc(100% + 8px) (or left), and color border-left or border-right on the arrow. In right-to-left pages, logical properties like inset-inline-end save you from writing both.

Limits of the pseudo-element approach

This tooltip is fine for decoration, but it has real weaknesses:

  • Accessibility is unreliable. Generated content isn't a proper description. Some browsers add it to the button's accessible name, others ignore it, and there's no link between trigger and tip.
  • No Escape key. Accessibility guidelines (WCAG 1.4.13) say content that appears on hover or focus should be dismissible without moving the pointer, hoverable (you can move the pointer onto it without it vanishing), and persistent until dismissed. CSS alone can't handle Escape.
  • Clipping. If any ancestor has overflow: hidden, the tooltip is cut off at its edge.
  • No elements inside. attr() gives plain text only.

An accessible tooltip with a real element

The robust pattern uses an actual element for the tip, connected to its trigger:

HTML
<button aria-describedby="tip-archive">Archive</button>
<span role="tooltip" id="tip-archive">Moves the file out of your inbox</span>

aria-describedby makes screen readers read the tooltip text after the button's name ("Archive, button, Moves the file out of your inbox"). The text is available even when the tip is visually hidden. role="tooltip" labels its purpose.

Naming vs describing. For an icon-only button, the tooltip text is the name. Use aria-labelledby (or an aria-label with the same text) instead of aria-describedby, so the button isn't announced as nameless. Icons in CSS covers icon-button labels.

A few lines of JavaScript add the Escape key, the one thing CSS can't do:

An accessible tooltip with Escape to close

This version meets all three WCAG rules. Because the hover selector is on the wrapper, moving the pointer from the button onto the tooltip keeps it open (hoverable). It stays until you leave (persistent), and Escape hides it (dismissible).

The arrow here is a rotated square instead of a border triangle. It inherits the bubble's background, so changing one color updates both, and it can have a border or shadow, which border triangles can't. Another option is a small clip-path: polygon() triangle.

Toggletips for touch screens

On phones there's no hover, and focusing a button usually activates it. When the hint matters, use a toggletip: a small "i" or "?" button that shows the tip when tapped. The popover attribute makes it simple. It closes on outside tap and Escape, and it renders in the top layer, so no overflow can clip it:

A toggletip with popover

The positioning uses anchor positioning, which attaches the popover to its button and flips it below when there's no room above. That lesson also builds a hover tooltip with anchors. Browsers without anchor positioning show the tip centered on screen, which is still readable.

Newer: hint popovers and interest invokers

Two newer features aim to make hover tooltips a built-in HTML feature:

  • popover="hint" creates a popover that doesn't close other open popovers (a tooltip shouldn't close the menu you're in). It shipped in Chromium browsers in 2025.
  • Interest invokers (the interestfor attribute) let a link or button show a popover on hover, focus or long-press, with built-in delays and dismissal. At the time of writing they're available only in recent Chromium browsers.

Until both work everywhere, treat them as enhancements on top of the patterns above, and check support with feature queries or in JavaScript.

Design tips

  • Keep the text short. One line, maybe two. If you need more, it's not a tooltip.
  • Add a short delay before showing (transition-delay: 300ms on the open state) so tips don't flash while the pointer crosses the page; hide them quickly.
  • Make them readable: at least 4.5:1 contrast, a comfortable font size, and enough padding.
  • Don't cover what the user is reading. Place tips where they won't hide the field or text in question.
  • Respect reduced motion. Fade, but skip sliding or bouncing for users who prefer reduced motion (see Motion and Performance).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which content belongs in a tooltip?

    Tooltips are for short, supplementary text. Essential instructions and errors must be visible, and interactive content needs a popover or dialog.
  2. 2. In a CSS-only tooltip, what does content with attr(data-tip) do?

    attr() reads an attribute value as a string for content. It doesn't create elements or reliably set any accessibility information.
  3. 3. How does aria-describedby help a tooltip?

    The attribute links the trigger to the tooltip element by id, so assistive technology announces the description even when the tip isn't visible.
  4. 4. Which WCAG requirement can CSS alone NOT satisfy for hover tooltips?

    CSS can show tips on hover and focus and keep them open while hovered, but reacting to Escape needs a few lines of JavaScript (or a popover).
  5. 5. Why use a popover-based toggletip instead of a hover tooltip on mobile?

    A toggletip works with taps, light-dismisses automatically, and renders in the top layer so it is never clipped.

Summary

  • Tooltips hold short, supplementary text; essential information must be visible without hovering.
  • A CSS-only tooltip uses content: attr(data-tip) on ::after, centering with left: 50% and translate: -50%, and width: max-content with a max-width.
  • Arrows are border triangles, rotated squares or clip-path triangles on a second pseudo-element.
  • Show tips on :hover and :focus-visible (or :focus-within), and use pointer-events: none on invisible tips.
  • For accessibility, use a real element with role="tooltip", link it with aria-describedby (or aria-labelledby for icon names), keep it hoverable, and let Escape dismiss it.
  • On touch screens, prefer a popover toggletip; popover="hint" and interest invokers are newer, Chromium-first enhancements.

Next: Pagination and Breadcrumb Styling, where you style page links, breadcrumbs and button groups.