TOOLTIP: Informational overlay that appears on hover or keyboard focus
PLACEMENTS: Top | Bottom | Left | Right
ALIGNMENTS: Start | Center | End
SIZES: Small | Default | Large

Use tooltips to provide brief, supplementary descriptions for UI elements. They appear on hover and keyboard focus, and auto-reposition when near viewport edges. Requires Stimulus controller.

Default Usage

Default: Tooltip appears above the element, centred. Add data-controller="tooltip" and data-tooltip-content-value to any element.

<button class="tw-btn tw-btn-primary" data-controller="tooltip" data-tooltip-content-value="Save your changes">Save</button>

Placements

Placements: Control where the tooltip appears relative to its trigger using data-tooltip-placement-value. Options: top (default), bottom, left, right.

<button data-controller="tooltip" data-tooltip-content-value="..." data-tooltip-placement-value="bottom">...</button>

Alignment

Alignment: Fine-tune positioning along the cross axis using data-tooltip-align-value. Options: start, center (default), end. Works with all placements.

Top placement

Bottom placement

Left placement

Right placement

<button data-controller="tooltip" data-tooltip-content-value="..." data-tooltip-placement-value="right" data-tooltip-align-value="start">...</button>

Size Variants

Sizes: Use data-tooltip-size-value to control tooltip size. Options: sm (compact), default, lg (prominent).

<button data-controller="tooltip" data-tooltip-content-value="..." data-tooltip-size-value="sm">...</button>

Auto-Repositioning

Auto-flip: When a tooltip would overflow the viewport, it automatically flips to the opposite side. Try hovering the buttons near the edges of the preview area. The tooltip also nudges along the cross axis to stay within bounds.

Keyboard Accessibility

Keyboard: Tooltips appear on keyboard focus (focusin) and dismiss on blur (focusout) or Escape key. Tab through the elements below to see tooltips triggered by keyboard focus.

Help
<input class="tw-form-control" data-controller="tooltip" data-tooltip-content-value="...">

Long Content

Wrapping: Tooltips have a max width of 320px (max-w-xs) and wrap text automatically. Keep tooltip text concise, but longer descriptions are supported.

Real-World Examples

Practical uses: Icon-only buttons that need a text label, truncated content that needs the full version, and form fields with supplementary guidance.

Truncated text with full content in tooltip

Application for Year 7 Entry — September 2026 Intake

Form field with tooltip helper

<button class="tw-btn tw-btn-icon" aria-label="Settings" data-controller="tooltip" data-tooltip-content-value="Settings">...</button>