Tooltip

You’re sending rent from your banking app on your phone. Next to IBAN there’s a little ⓘ. You tap it. Nothing. You tap it again, harder. Still nothing. On the laptop the same ⓘ shows a helpful bubble, but only when the mouse is over it. The developer tested with a mouse, and never noticed that phones don’t have one.

Tooltips look like the most harmless component on the page: a few words in a dark bubble. But they depend on how the user points at things (mouse, finger, keyboard, screen reader), they float over other content, and they love to hide behind screen edges. That makes them a great place to find bugs.

What is a tooltip?

A tooltip is a small, temporary bubble of plain text that describes the element it’s attached to. It appears when the user hovers over the element with a mouse, moves keyboard focus to it, or (on touch screens) long-presses it. It disappears when they move away.

You’ll usually see tooltips used to:

• Name icon-only buttons: Archive, Share, Add to wishlist.
• Show keyboard shortcuts: Bold (Ctrl+B).
• Add a short hint next to a form label: “Shown on the recipient’s statement”.
• Show the full text of something that is cut off, like a long file name.

Anatomy

Tooltip, toggletip, toast or inline help?

Several components show “a bit of extra text”. Picking the wrong one is one of the most common tooltip problems.

Pattern	Opens when	Content	Good for
Tooltip	Hover, focus, long-press	A few words of plain text	Naming icons, shortcuts
Toggletip / popover	Click or tap	Text, links, buttons	Explanations, “Learn more”
Toast	The app shows it after an action	A status message, maybe “Undo”	“Transfer sent”
Inline help	Always visible	Text under a field	Rules users need to succeed
Coachmark	Once, during onboarding	Title, text, close button	Pointing at a new feature

Designs & variants

Try each one with the mouse, with only the keyboard (Tab, Esc), and on a phone (press and hold the Android icons).

Your order has shipped

Nordic Home · 09:14

Trail runner 2

Instant transfer

+€0.50

Money arrives in seconds

Notes

Start a new note

Tap here to write something new. Your notes sync across devices.

Hover, focus, long-press: touch screens have no hover

A tooltip has to work for every way people point at things. This is where most tooltip bugs come from.

Input	How the tooltip should open	How it should close
Mouse / trackpad	Hover, after a short delay	Pointer leaves (trigger and tooltip), or Esc
Keyboard	Tab focus, immediately	Focus moves on, or Esc
Touch (Android)	Long-press the icon button	Shortly after the finger lifts
Touch (iPhone, web)	Usually not at all, so don’t hide anything important in it	n/a
Screen reader	Never “opens”; the text is read as the name or description	n/a

The key lesson: on a phone, a hover-only tooltip doesn’t exist. A tap is not a hover. If the information matters on mobile, it must be visible, or opened with a tap as a toggletip.

Delay and dismissal: WCAG 1.4.13

Mouse tooltips usually wait a few hundred milliseconds before appearing, so they don’t flash while the pointer crosses the page. Keyboard focus should show them right away.

Once a tooltip is visible, WCAGWCAGThe Web Content Accessibility Guidelines, the main international standard for accessibility.Open in glossary → success criterion 1.4.13 Content on Hover or Focus (level AA) asks for three things:

Positioning and screen edges

A tooltip normally appears above (or below) its trigger, centered. Near an edge there is no room, so a good tooltip:

• Shifts sideways to stay fully on screen, while its arrow keeps pointing at the trigger.
• Flips to the other side when there’s no room above (for example, under a toolbar at the top of the page).
• Is not clipped by a parent with hidden overflow, a scrolling list, the notch or the safe areaSafe areaThe part of the screen not covered by the notch, Dynamic Island, rounded corners or home indicator.Open in glossary →.

Test the first and last icon in every toolbar, at the narrowest viewportViewportThe visible area of a web page in the browser window or on the device screen.Open in glossary → and with long translations.

Plain text only

A tooltip disappears when the pointer or focus leaves the trigger, so anything interactive inside it is a trap: a mouse user has to “chase” the link, a keyboard user can’t Tab into it, and a touch user never sees it. If the bubble needs a link or a button, it should be a toggletip or popover that opens on click and stays open.

Icon buttons still need a name

A tooltip that says “Delete” looks like the button’s name, but a screen readerScreen readerSoftware that reads the screen aloud for blind and low-vision users, like VoiceOver or TalkBack.Open in glossary → only uses it if the code connects them. An icon button needs an accessible name of its own. Otherwise it’s announced as just “button”. The tooltip is the visual version of that name, not a replacement for it.

Dev note

aria-label="Delete" on the web, accessibilityLabel on iOS, contentDescription on Android.

Onboarding coachmarks

Coachmarks (or “tips”) point at a feature the first time a user sees a screen: “Tap here to start a new note”. They’re related to tooltips, but appear without hovering. Test that they:

• Have a clear close button (with a name) and close with Back / Esc.
• Don’t come back after being dismissed, after a restart or an update (unless that’s the plan).
• Point at the right thing, on every screen size and in landscape.
• Don’t block the very button they’re pointing at, and don’t stack three on top of each other.

When to use it

Tooltips are a good choice when:

• You need to name an icon-only button for mouse and keyboard users (and the button already has an accessible name).
• The hint is nice to know, not need to know: the user can succeed without ever seeing it.
• The text is short: a few words, one short sentence at most.
• The product is used with a mouse or keyboard (desktop web, tablets with a pointer), or on Android, where long-press shows it.

Good and bad uses

Common bugs

#	Bug	What you see	Severity
1	Hover only	Nothing on Tab, nothing on tap	Medium–High
2	Clipped at the edge	Half the text is cut off near the screen edge	Medium
3	Not hoverable	It vanishes when the pointer moves towards it	Medium (fails WCAG)
4	Can’t dismiss	Esc does nothing; it covers the next field	Medium (fails WCAG)
5	Interactive content	A “Learn more” link that can’t be clicked or reached	Medium
6	Icon button with no name	Screen reader says just “button”	High (for affected users)
7	Sticky tooltip	Stays on screen after scrolling, closing a dialog or tapping elsewhere	Low–Medium
8	Flicker	Tooltips flash on and off while the mouse crosses a toolbar	Low
9	Wrong or stale text	“Mark as read” on a message that’s already read	Medium
10	Coachmark returns	A dismissed onboarding tip shows up again after every restart	Low–Medium

Stress-test it

This mail app toolbar has correct tooltips. Use the settings to break them on purpose and watch the WCAG check. Try it with the mouse, then only with the keyboard, then on your phone.

Hover delay

0400 ms1 s

Hoverable

OnOff

Esc closes

OnOff

Edge handling

OnOff

Your order has shipped

Nordic Home <orders@nordic.example> · 09:14

Hi Anna, good news: order #4821 is on its way. Track it with DHL using the code JJD0099 1234 5678.

Mouse: hover · Keyboard: Tab, then Esc · Touch: press and hold

WCAG 1.4.13 check

• Dismissible. Esc hides it without moving the pointer or focus.
• Hoverable. You can move the pointer onto it (e.g. to zoom in on it).
• Persistent. Stays until the pointer leaves, focus moves or Esc. No timer.

Screen reader would say

Tab to a toolbar button to hear it…

Event log

• Hover, Tab or long-press a button.

Things to try: turn Edge handling off and hover Archive and Snooze at the edges. Turn Hoverable off and try to move the pointer onto the long Mute tooltip. Set the delay to 0 and sweep the mouse across the toolbar: tooltips flash on and off. Tab to a button: keyboard focus never waits for the delay.

Find the bug

This “Send money” page in a web bank has six tooltip bugs. Explore it like a tester:

• Use the mouse on every icon: hover, then try to move onto the bubble.
• Then use only the keyboard: Tab through the page and press Esc when something covers the form.
• Open the ? next to Instant transfer and try its link.
• Read the screen reader panel for every button.
• If you can, open this page on a phone and tap the info icons.

🐞 Bug hunt: Send money

This demo has 6 hidden bugs. Explore it like a tester, then check your findings.

Found0/6

bank.example.com/transfer

Send money

From Main account€1,240.50

Recipient name

IBAN

Amount (€)

Reference (optional)

Instant transfer

Fee€0.00

Review transfer

Tester tools

Reload page

Screen reader would say

Tab through the page to hear each control…

Test with the mouse, then only the keyboard (Tab, Esc). On a phone, tap the info icons.

1. 1

   Hint: Tab to the ⓘ next to IBAN, or tap it on a phone.

   The IBAN tooltip only works with a mouse

   The tooltip is opened only by pointerenter with a mouse. Keyboard focus and taps do nothing, and the text is not linked to the button, so screen readers don’t hear it either. Expected: it opens on hover and focus, and the important format hint is also visible as inline help for touch users.

   Reveal answer✓ I found this
2. 2

   Hint: Hover the ⓘ next to the fee at the right.

   The fee tooltip is cut off at the right edge

   The bubble starts at the icon’s left edge and grows to the right, with no collision handling, so the page clips it mid-sentence. Expected: the tooltip shifts or flips to stay fully visible, with the arrow still pointing at the icon.

   Reveal answer✓ I found this
3. 3

   Hint: Hover the ⓘ next to Reference and move the mouse up onto the bubble.

   The reference tooltip disappears when you move onto it

   It hides the moment the pointer leaves the icon, and there is a 12 px gap to cross. Users with screen magnifiers can’t read it. This fails WCAG 1.4.13 hoverable. Expected: the pointer can move onto the tooltip and it stays open.

   Reveal answer✓ I found this
4. 4

   Hint: Click into Amount, then press Esc. Then try to click the Reference field.

   The amount hint can’t be dismissed and covers the next field

   The hint stays open while Amount has focus and covers the Reference field. Esc does nothing, and the first click on the covered field only closes the hint. This fails WCAG 1.4.13 dismissible. Expected: Esc hides it, and it doesn’t cover inputs the user needs next (or it is shown as inline help).

   Reveal answer✓ I found this
5. 5

   Hint: Open the ? next to Instant transfer and click the link. Then try to reach it with Tab.

   The “See all fees” link can’t be used

   The “click outside closes” code only ignores the ? button, so pressing the link counts as an outside click and closes the bubble before the link activates. The link also has tabindex="-1", so keyboard users can’t reach it. Expected: links belong in a toggletip or popover that stays open, accepts clicks and is reachable with Tab.

   Reveal answer✓ I found this
6. 6

   Hint: Tab to the QR icon at the top and read the screen reader panel.

   The QR button has no accessible name

   The tooltip shows “Scan QR code”, but the button has no aria-label and the tooltip isn’t linked to it, so a screen reader announces only “button”. Expected: the button has its own name (“Scan QR code”), and the tooltip just shows it visually.

   Reveal answer✓ I found this

How to test it

Checklist

Tooltip test checklist

0 of 13 checked

Copy

• Mouse: the tooltip appears on hover after a short delay, without flickering across a toolbar
• Keyboard: it appears immediately on Tab focus and hides when focus moves on
• Esc hides it without moving the pointer or focus (dismissible)
• The pointer can move onto the tooltip without it disappearing (hoverable)
• It stays visible until the user moves away or dismisses it, with no auto-hide timer (persistent)
• Touch: important information is visible or opens with a tap; Android icon buttons show tooltips on long-press
• It is never clipped: check the first and last items, narrow screens, scrolling containers and long translations
• It contains plain text only; anything with a link or button is a toggletip or popover
• Every icon button has its own accessible name; the screen reader never says just "button"
• Extra tooltip text is linked as a description and read by the screen reader
• It disappears on scroll, after closing a dialog or navigating, and never sticks on screen
• The text is correct and up to date for the current state (e.g. "Mark as unread" vs "Mark as read")
• Onboarding tips have a close button, point at the right element and stay dismissed

Example test cases

Tools

• DevTools › Elements: right-click › Force state › :hover or :focus keeps CSS tooltips open while you inspect them. For JavaScript tooltips, use Emulate a focused page (Rendering panel) so they don’t close when you click into DevTools.
• Accessibility pane: shows each button’s computed Name and Description. An empty name on an icon button is bug #6.
• Device toolbar: test at 360 px wide and with touch emulation. Remember that emulation is not a real finger: confirm touch behavior on a real deviceReal deviceA physical phone or tablet used for testing, as opposed to an emulator or simulator.Open in glossary →.
• Screen readers: VoiceOver (Mac and iPhone), TalkBack (Android), NVDA (Windows, free).

Accessibility

• Name first. Every icon-only button needs an accessible name.
  Dev note

  On the web that’s aria-label (or a tooltip linked with aria-labelledby). On iOS it’s accessibilityLabel; on Android, contentDescription. For Android toolbar menu items, the item’s title usually serves as both the spoken name and the long-press tooltip.
• Link extra text as a description. A screen reader reads a tooltip that adds information after the name.
  Dev note

  The tooltip gets role="tooltip" and is referenced with aria-describedby from the trigger.
• Never rely on title. The native title tooltip doesn’t show on keyboard focus or touch, can’t be styled, and screen readers handle it inconsistently.
• KeyboardKeyboard navigationUsing a website with only the keyboard: Tab to move, Enter or Space to activate, Esc to close.Open in glossary →. The trigger must be focusable; focus shows the tooltip, Esc hides it, and focus never moves into a tooltip. If users need to Tab into it, it’s a popover.
• WCAG 1.4.13. Dismissible, hoverable, persistent (see above). This is a level AA criterion, so most accessibility audits check it.
• Contrast and size. Tooltip text needs 4.5:1 contrast against its bubble, and must still fit at 200% zoom and the largest text size.

Mobile vs web

iOSAndroidWeb

• iPhone apps rarely use tooltips: there’s no hover, and Apple’s guidelines prefer clear labels and standard icons. Icon buttons still need a label for VoiceOver.
  Dev note

  That’s accessibilityLabel.
• On the Mac (including Mac Catalyst apps), apps can show a hover tooltip; on iPad with a trackpad or mouse, check what the app’s iPadOS version actually shows.
  Dev note

  SwiftUI’s .help("…") shows the hover tooltip.
• For feature hints, apps use TipKit (iOS 17+): popover tips and inline tips. Test that they close, stay closed, and don’t cover what they point at.
• Larger hints usually live in a popover or a bottom sheet.

• Android has built-in tooltips. They appear on long-press and on mouse hover.
  Dev note

  android:tooltipText, TooltipCompat; TooltipBox with PlainTooltip / RichTooltip in Compose.
• Action bar / toolbar icons show their title as a tooltip on long-press. Check that the long-press doesn’t also trigger the action.
• Material 3 rich tooltips can include a title and an action; persistent ones stay open until dismissed. Test them like popovers.
• Test with TalkBack: icon buttons must have a description.
  Dev note

  That’s contentDescription.

• Test hover, focus and touch. Use real phones; mobile browsers have no hover, and taps can “stick” a hover state.
• Check edges, scrolling containers and zoom: the tooltip must stay visible and move with its trigger.
• Inspect the markup: role="tooltip", aria-describedby or aria-labelledby, no interactive content, no reliance on title.
  Dev note

  Newer HTML features like the Popover API (popover attribute) help build toggletips and popovers that open on click and close with Esc.

Check your understanding

Quick quiz

0/5 answered · 0 correct

1. 1.The ⓘ next to "IBAN" works with a mouse on desktop. What is the most important thing to test next?

   AThe tooltip colorBKeyboard focus and a tap on a phoneCThe hover delay in millisecondsDThe tooltip font

2. 2.Which of these belongs in a tooltip?

   APassword rules users must followB"Learn more" and "Got it" buttonsCThe name of an icon button: "Archive"DAn error message after saving

3. 3.A tooltip disappears as soon as you move the mouse towards it. Which WCAG 1.4.13 requirement fails?

   ADismissibleBHoverableCPersistentDNone, this is fine

4. 4.An icon button shows the tooltip "Delete", but VoiceOver says only "button". What is missing?

   AA longer tooltipBAn accessible name (e.g. aria-label) on the buttonCA hover delayDA darker tooltip color

5. 5.How do Android apps usually show the tooltip of a toolbar icon button?

   AOn long-pressBOn a single tapCOn a double tapDThey never do

Key takeaways

• A tooltip is a short, plain-text hint that appears on hover, keyboard focus or long-press. Links and buttons belong in a toggletip or popover.
• Touch screens have no hover. Never hide need-to-know information in a hover-only tooltip.
• WCAG 1.4.13: tooltips must be dismissible (Esc), hoverable and persistent.
• Test the edges: tooltips must shift or flip, never get clipped.
• Every icon button needs its own accessible name. The tooltip is just the visible version of it.