Tooltip

One class, one attribute: add class="af-tooltip" and aria-label="tooltip text". The visual tooltip uses the same text as the element’s accessible name, so screen readers and keyboard users get the same content. The tooltip appears on hover and focus.

Markup

<button class="af-btn af-tooltip" aria-label="Save the document">
  Save
</button>
<!-- Icon-only: aria-label is the tooltip and the accessible name -->
<button type="button" class="af-btn af-tooltip" aria-label="Close">
  <span aria-hidden="true">
    ×
  </span>
</button>

Placement

Add a side modifier so the tooltip appears on the chosen side of the trigger. Default is top; no modifier needed. The bubble has max-width: var(--af-tooltip-width, 25ch) and text wraps.

.af-tooltip-top – above (default)
.af-tooltip-right – to the right
.af-tooltip-bottom – below
.af-tooltip-left – to the left

Top (default)

<button class="af-btn af-tooltip af-tooltip-top" aria-label="Tooltip above">
  Hover me
</button>

Right

<button class="af-btn af-tooltip af-tooltip-right" aria-label="Tooltip on the right">
  Hover me
</button>

Bottom

<button class="af-btn af-tooltip af-tooltip-bottom" aria-label="Tooltip below">
  Hover me
</button>

Left

<button class="af-btn af-tooltip af-tooltip-left" aria-label="Tooltip on the left">
  Hover me
</button>

The tooltip bubble’s max width is controlled by the CSS variable --af-tooltip-width (default 25ch). Override it on :root for all tooltips, or on the trigger (or a wrapper) for a single tooltip.

Global override:

:root {
  --af-tooltip-width: 35ch;
}

Per tooltip (inline or class):

<button class="af-btn af-tooltip" aria-label="A longer description that can wrap across more characters" style="--af-tooltip-width: 35ch">
  Info
</button>

On any element

The trigger can be a div, span, or any focusable element. Ensure it’s keyboard-focusable if you want the tooltip on focus (e.g. add tabindex="0" for non-interactive elements).

<div class="af-tooltip" aria-label="This is the tooltip content" tabindex="0">
  Hover or focus
</div>

Accessibility summary

Need	Approach
Keyboard users see tooltip	✅ Tooltip shows on `:focus` / `:focus-visible` (same as hover).
Screen reader gets tooltip text	✅ Same text from `aria-label` (element’s accessible name).
Dismissible (e.g. Escape)	Not supported with pure CSS; use a JavaScript tooltip if you need WCAG 1.4.13 (Content on Hover or Focus) fully.