Description
What it does
Shows a small floating label with supplementary text when a user hovers over or focuses a trigger element. The tooltip disappears when the user moves away or shifts focus.
Where it appears
Icon-only action buttons in data tables (such as edit, archive, or export stakeholder records), form field labels that need brief clarification, and toolbar controls in the consultation builder.
Why it exists
Government interfaces often require dense layouts where full button labels would consume too much horizontal space. Tooltips let teams use icon-only controls without sacrificing clarity, while keeping the interface uncluttered for experienced users.
Anatomy
| Part | Required? | Notes |
|---|---|---|
| Trigger | Required | The interactive element — button, icon, or link — that the tooltip is anchored to. Must be focusable and receive the aria-describedby pointing to the tooltip. |
| Tooltip container | Required | The floating surface that holds the label text. Positioned above the trigger by default, with automatic repositioning if it would overflow the viewport. |
| Label text | Required | Short, plain-language description. Maximum two lines. Should not duplicate the visible label if the trigger already has one. |
| Arrow / caret | Optional | A small directional indicator pointing from the tooltip container toward the trigger. Helps clarify the relationship when the tooltip repositions to a non-default placement. |
Variants
Default
Neutral informational label
Use for the majority of tooltip needs — clarifying an icon button action, providing a short hint for a form field, or surfacing a full value that is truncated in the UI.
Top placement
Tooltip appears above the trigger
Default placement. Use when there is sufficient vertical space above the trigger and the content below must remain unobstructed.
Bottom placement
Tooltip appears below the trigger
Use when the trigger is near the top of the viewport or a scrollable region and the tooltip would otherwise be clipped.
Start (left) placement
Tooltip appears to the left of the trigger
Use for triggers at the right edge of a panel or column where vertical placements would overflow.
End (right) placement
Tooltip appears to the right of the trigger
Use for triggers at the left edge of a sidebar or navigation rail.
States
| State | Behaviour |
|---|---|
| Hidden | Default state. The tooltip container is not rendered in the visible layout. The trigger is interactive as normal. |
| Visible (hover) | Tooltip appears after a short delay (approximately 300ms) when the pointer enters the trigger. Dismissed immediately when the pointer leaves the trigger or the tooltip container. |
| Visible (focus) | Tooltip appears immediately when the trigger receives keyboard focus, with no delay. Dismissed when the trigger loses focus. |
| Persistent (touch) | On touch devices, a single tap toggles tooltip visibility. A second tap on the trigger, or a tap elsewhere, dismisses it. |
| Disabled trigger | If the trigger element is disabled, the tooltip must still be reachable by keyboard. Wrap a disabled button in a focusable container (e.g. a span with tabindex='0') and attach the tooltip to the wrapper, not the button. |
Usage guidelines
When to use
- Clarifying the action of an icon-only button, such as an archive or export icon in the stakeholder table.
- Providing a short hint for a form field label where inline helper text would add too much visual weight.
- Revealing the full value of truncated text in a narrow table cell, such as a long stakeholder organisation name.
- Explaining abbreviations or status codes used in consultation dashboards that may not be familiar to all staff.
When not to use
- Do not place essential information — required field indicators, error messages, or critical instructions — inside a tooltip. Use inline helper text, validation messages, or visible labels instead.
- Do not use a tooltip to replace a visible label on an interactive element if space permits. Visible labels are always preferable for accessibility and discoverability.
- Do not use a tooltip for content longer than two short lines. Consider a popover or side panel for richer contextual content.
- Do not attach a tooltip to non-interactive elements such as plain text or decorative icons. Screen reader users navigating by keyboard will not encounter them.
Do / Don't
Do
Keep tooltip text concise — a single verb phrase or short sentence. For example: 'Archive stakeholder' or 'Consultation closes 30 June'.
Don't
Don't write multi-sentence explanations or include links, form controls, or rich content inside a tooltip.
Do
Ensure the tooltip trigger has a visible focus indicator meeting the 3px --op-color-interactive-focus ring requirement.
Don't
Don't rely solely on the tooltip to convey state — for example, don't use tooltip text as the only indicator that a button is disabled.
Do
Use the tooltip to complement an aria-label on icon-only buttons, not replace it. The aria-label names the button; the tooltip can add brief context.
Don't
Don't omit the aria-label on an icon-only button and expect the tooltip alone to provide an accessible name.
Layout & Spacing
Tooltip container padding: --op-space-8 (8px) vertical, --op-space-12 (12px) horizontal. Offset from trigger: --op-space-8 (8px) gap between trigger edge and tooltip surface. Maximum width: 240px (fixed, not a token). Text wraps within this constraint. Arrow size: 6px base, 6px height — not token-driven; set directly on the wa-tooltip component.
Tokens
| Part | Token | Value |
|---|---|---|
| Tooltip container background | --op-color-text-primary | Inverted surface — uses the text colour as background to create high contrast against the page. Adjust if the theme defines a dedicated tooltip-bg token. |
| Tooltip label text | --op-color-bg-primary | Inverted text — uses the page background colour as text on the dark container surface. |
| Tooltip border radius | --op-radius-sm | 4px. Keeps the tooltip visually compact and distinct from card or modal surfaces. |
| Trigger focus ring | --op-color-interactive-focus | 3px solid ring applied to the trigger element on focus, not the tooltip itself. |
| Label typography | --op-text-xs | 12px / font-body. Tooltip text is intentionally smaller than body copy to signal its supplementary role. |
Engineering notes
- Use the wa-tooltip web component. Set the content attribute for simple text labels, or use the default slot for slightly richer content (still no interactive elements).
- Always pair wa-tooltip with an aria-describedby relationship. The wa-tooltip component handles this automatically when wrapping the trigger as a child; verify the generated DOM in your browser's accessibility tree.
- For disabled buttons, the HTML disabled attribute prevents focus and therefore hides the tooltip from keyboard users. Wrap the disabled button in a <span tabindex='0'> and attach wa-tooltip to the span. Include aria-disabled='true' on the button.
- Respect prefers-reduced-motion by suppressing the tooltip fade-in animation. Web Awesome honours this via its animation system; confirm in your integration that the host page does not override the media query.
- Do not nest interactive content (links, buttons, form controls) inside a tooltip. Use wa-popover for interactive floating panels.
- When programmatically showing or hiding tooltips (e.g. on long-press), use the show() and hide() methods on the wa-tooltip element rather than manipulating display or visibility directly.
Keyboard interaction
| Key | Action |
|---|---|
| Tab | Moves focus to the tooltip trigger. The tooltip becomes visible immediately on focus. |
| Shift+Tab | Moves focus away from the trigger. The tooltip is dismissed. |
| Escape | Dismisses a visible tooltip without moving focus away from the trigger. Required for WCAG 1.4.13 (Content on Hover or Focus). |
Why it matters
Government digital services must meet WCAG 2.1 AA. Many users of Open Point and Social Point rely on keyboard navigation or screen readers. A tooltip that is only reachable by pointer, or that disappears the moment focus moves to it, creates a barrier. Tooltip content must be persistent enough for a user to read it, and dismissible without losing their place.
Focus
The tooltip trigger must have a visible focus ring: 3px solid --op-color-interactive-focus, with a 2px offset to prevent the ring from obscuring the trigger border. The tooltip container itself is not focusable and does not receive keyboard focus. All tooltip text must be surfaced via aria-describedby on the trigger, not by focusing the tooltip. When focus leaves the trigger (Tab or Shift+Tab), the tooltip dismisses immediately.
ARIA
| Role or attribute | When to use | Example |
|---|---|---|
role="tooltip" | Applied to the tooltip container element. Identifies the element as a tooltip to assistive technologies. | <div id="tip-archive" role="tooltip">Archive this stakeholder record</div> |
aria-describedby | Applied to the trigger element, referencing the tooltip container's id. Causes screen readers to announce the tooltip text after the element's accessible name. | <button aria-label="Archive" aria-describedby="tip-archive"><wa-icon name="archive"></wa-icon></button> |
aria-label | Applied to the trigger when it is an icon-only button. Provides the accessible name independently of the tooltip. The tooltip text should add context, not repeat the label. | <button aria-label="Export to CSV" aria-describedby="tip-export">...</button> |
aria-disabled | Applied to a button that is visually disabled but must remain focusable so its tooltip is reachable. Use in conjunction with a focusable wrapper span. | <span tabindex="0" aria-describedby="tip-disabled"><button aria-disabled="true" disabled>...</button></span> |
Contrast
The inverted tooltip surface (--op-color-text-primary background, --op-color-bg-primary text) must meet a minimum contrast ratio of 4.5:1 against the tooltip text. Verify this holds in both light and dark themes if your deployment supports theme switching. The trigger element's visible focus ring (--op-color-interactive-focus, green-400) must maintain 3:1 contrast against the adjacent background colour per WCAG 1.4.11 (Non-text Contrast).
Touch targets
The tooltip trigger must meet the 44x44px minimum touch target size. This is especially important for icon-only buttons in the stakeholder table — ensure icon buttons have sufficient padding applied via the button component's size variants, not by relying on the icon glyph size alone.
Things to avoid
- Do not use tooltip text as the sole accessible name for a control. The trigger must have its own aria-label or visible label text.
- Do not make tooltip content appear only on hover with no keyboard equivalent. Every tooltip must also appear on focus.
- Do not auto-dismiss a tooltip after a fixed timeout while it is still in focus or being hovered. This prevents users who read slowly from accessing the content.
- Do not include plain text links or buttons inside a tooltip. They cannot be reached by keyboard and will trap screen reader users.
- Do not use a tooltip on a decorative icon that conveys no information. Reserve tooltips for functional, interactive triggers.