ARIA tooltip needs an accessible name

ARIA tooltip elements must include an accessible name

Every element with role=tooltip needs a discernible accessible name.

Tooltips are often revealed on hover or focus to explain controls. If the tooltip node has no accessible name, assistive technologies cannot announce its purpose or content, leaving users without essential context.

Why It Matters

Users of screen readers rely on programmatic names to perceive on-screen help. A tooltip without a name is effectively silent, so the associated control may be unclear or risky to operate.

This impacts blind users and people with low vision using screen readers. It can also hinder users with cognitive disabilities who depend on concise guidance.

Complies with WCAG 2.2, especially 4.1.2 (Name, Role, Value).

Common Causes

• Empty tooltip containers with no text content.
• aria-label present but blank or whitespace-only.
• aria-labelledby pointing to an ID that does not exist or references an element with no accessible text.
• Tooltip text injected only via CSS (e.g., ::before content) or background images.
• Tooltip content rendered after interaction but not present in the DOM when tested.

How to Fix

1. Provide a textual name on the tooltip element:
   • Use meaningful inline text content inside the tooltip element; or
   • Add aria-label with concise, descriptive text; or
   • Use aria-labelledby to reference another element that contains the text.
2. If using aria-labelledby:
   • Ensure the referenced element exists, is unique, and contains non-empty accessible text.
   • Do not reference hidden or decorative-only nodes.
3. If considering the title attribute:
   • Acceptable for some automated checks, but not recommended. Many screen readers do not reliably announce title, and it is not usable on touch devices. Prefer text content, aria-label, or aria-labelledby.
4. Keep the tooltip in the DOM with its name available when it may be triggered.
   • If content is added dynamically, populate accessible text at the same time the tooltip is created.
5. Associate the trigger with the tooltip so users hear it at the right time:
   • Add aria-describedby on the trigger pointing to the tooltip’s id.
   • Ensure show/hide behavior does not remove the tooltip text from the accessibility tree when needed.

Recommendation: Keep tooltip text short and specific (one short sentence or phrase). Avoid duplicating the control’s name; add new, helpful information.

How to Test

Keyboard check:

• Tab to each control that displays a tooltip. The tooltip should appear on focus and remain long enough to read.
• Confirm focus is not trapped and dismissing the tooltip is possible with Esc or by moving focus.

Screen reader check (NVDA/JAWS/VoiceOver):

• Focus the trigger. Verify the tooltip text is announced as a description (via aria-describedby) or when the tooltip itself is navigated.
• Inspect the tooltip node in the Accessibility panel; confirm it has a non-empty computed name.

Mobile/touch check:

• Use a screen reader (TalkBack/VoiceOver). Focus the trigger via swipe. Ensure the tooltip text is announced.
• Confirm that information conveyed only via hover is also available on focus/touch.

Quick checklist:

• Each role=tooltip element has a non-empty accessible name.
• aria-label is meaningful and not empty or whitespace.
• aria-labelledby references valid, non-empty text.
• Tooltip text is not provided only via CSS or images.
• Trigger references tooltip with aria-describedby.
• Tooltip content is concise and helpful.

Good Example

<button type="button" aria-describedby="tip-uid" id="uid-btn">Username</button>
<div role="tooltip" id="tip-uid">Use 6–20 characters; letters and numbers only.</div>

<!-- Variant using aria-labelledby -->
<p id="uid-help" class="visually-hidden">Use 6–20 characters; letters and numbers only.</p>
<div role="tooltip" id="tip-uid-alt" aria-labelledby="uid-help"></div>

Bad Example

<!-- Empty tooltip (no name) -->
<div role="tooltip" id="t-empty"></div>

<!-- aria-label present but empty -->
<div role="tooltip" id="t-blank" aria-label=" "></div>

<!-- aria-labelledby points to missing/empty element -->
<div role="tooltip" id="t-missing" aria-labelledby="nope"></div>

Quick Checklist

• role=tooltip is present only on the tooltip element, not the trigger.
• Tooltip has text content, aria-label, or aria-labelledby with real text.
• Referenced IDs exist and contain readable text.
• Tooltip text is injected into the DOM and the accessibility tree when needed.
• Trigger uses aria-describedby to associate with the tooltip.
• Avoid relying on title; prefer robust naming with text/ARIA.