TooltipButton
A small circular icon button that triggers a tooltip with contextual help text. Use next to form fields, settings, or UI elements that benefit from an inline explanation. Don't use for primary or secondary actions.
Description
What it does
Renders a small circular icon button (typically a question mark or info icon) that displays a tooltip containing contextual help text when focused or hovered.
Where it appears
Inline with form field labels, section headings, settings panels, and data table column headers — anywhere a brief explanation reduces user uncertainty without cluttering the interface.
Why it exists
Government forms and stakeholder management workflows often include fields with policy-specific terminology or non-obvious requirements. The TooltipButton surfaces that context on demand, keeping the primary UI clean while reducing support queries.
Dependencies
Anatomy
| Part | Required? | Notes |
|---|---|---|
| Trigger button | Required | Circular button element, minimum 44x44px touch target. Renders a question mark or info icon. Acts as the accessible tooltip trigger via aria-describedby. |
| Icon | Required | Visual indicator of help context. Defaults to a question-mark glyph. Must remain visible at all interactive states. |
| Tooltip panel | Required | Floating container holding the help text. Appears above, below, or beside the trigger depending on available space. Dismissed on blur or Escape. |
| Tooltip arrow | Optional | Directional caret connecting the tooltip panel to the trigger. Aids spatial orientation, especially when the panel repositions. |
| Help text | Required | The explanatory copy inside the tooltip panel. Should be one to three short sentences. Do not place interactive elements (links, buttons) inside the tooltip. |
Variants
Default (question mark)
Signals that supplementary help is available for an adjacent field or concept.
Use next to form labels where the field purpose or accepted format needs clarification. Example — next to a 'Submission window' date field to explain the policy deadline rules.
Info
Signals factual context about a read-only value or system behaviour rather than user input guidance.
Use next to read-only data, status indicators, or calculated fields where the user needs to understand how a value is derived. Example — next to a stakeholder influence score to explain the scoring methodology.
States
| State | Behaviour |
|---|---|
| Default | Button is visible and interactive. Tooltip is hidden. Icon renders at --op-color-text-secondary. |
| Hover | Icon colour transitions to --op-color-interactive-hover. Tooltip appears after a short delay (150ms). Tooltip remains visible while the pointer is over either the trigger or the tooltip panel. |
| Focus | 3px focus ring appears using --op-color-interactive-focus. Tooltip appears immediately on focus. This is the primary accessible interaction path. |
| Active | Button depresses visually. Tooltip remains visible. |
| Tooltip visible | Tooltip panel is rendered in the DOM and visible. Pressing Escape or moving focus away dismisses the tooltip. |
| Disabled | Button is non-interactive. Icon renders at --op-color-text-disabled. Tooltip does not appear. Do not use disabled state unless the entire surrounding form context is also disabled — a disabled help button creates confusion. |
Usage guidelines
When to use
- Next to a form field label when the field name alone does not convey the expected format, policy constraint, or data source.
- Next to a column header in a data table when the metric or calculated value requires a brief methodology note.
- Next to a settings toggle or configuration option that has non-obvious downstream effects.
- Inside a section heading when the section applies only under specific conditions that are not obvious from the heading text.
When not to use
- Do not use as a substitute for clear, plain-language labels. If the label needs a tooltip to be understood, rewrite the label first.
- Do not place inside a tooltip panel — nested tooltips are inaccessible and disorienting.
- Do not use to surface critical warnings or errors. Use inline validation messages or an Alert component instead.
- Do not use for actions. If the icon button navigates somewhere or submits data, use an IconButton with an explicit label instead.
- Do not place multiple TooltipButtons consecutively. If a whole section needs explanation, use a callout or helper text block.
Do / Don't
Do
Write tooltip text in plain language, under 60 words. Start with the most important information.
Don't
Don't copy policy documents verbatim into tooltip text. Dense legal language defeats the purpose.
Do
Position the TooltipButton immediately after the label it describes, before any required-field indicator.
Don't
Don't place the TooltipButton at the end of a long line of controls where the spatial association is unclear.
Do
Ensure the tooltip text is also surfaced to screen readers via aria-describedby on the associated input, not just on the trigger button.
Don't
Don't rely on the tooltip trigger's title or aria-label alone to convey the help content to assistive technology users.
Do
Use the question-mark variant for input guidance and the info variant for read-only context.
Don't
Don't mix variants arbitrarily — inconsistent iconography within a single form erodes trust.
Layout & Spacing
Trigger button: Width and height: 24px visual size, 44x44px minimum touch target (padding compensates) Margin-left: --op-space-4 (4px) from the label it describes Vertical alignment: centre-aligned with label baseline
Tooltip panel: Padding: --op-space-8 (8px) --op-space-12 (12px) Max-width: 280px Border-radius: --op-radius-md (8px) Gap from trigger: --op-space-4 (4px)
Tokens
| Part | Token | Value |
|---|---|---|
| Trigger icon (default) | --op-color-text-secondary | Subdued so it doesn't compete with the label or field. |
| Trigger icon (hover/focus) | --op-color-interactive-hover | Matches the interactive green used across all hover states. |
| Focus ring | --op-color-interactive-focus | 3px solid outline, 2px offset. Never remove or suppress. |
| Tooltip background | --op-color-bg-inverse | Dark surface distinguishes the tooltip from the page background. |
| Tooltip text | --op-color-text-inverse | Ensures contrast against --op-color-bg-inverse. |
| Tooltip border | --op-color-border-default | Subtle 1px border improves legibility on light backgrounds near the panel edge. |
| Trigger icon (disabled) | --op-color-text-disabled | Communicates unavailability without removing the element from the layout. |
Engineering notes
- The TooltipButton is a composite: a `<button>` element wrapping a `<wa-icon>` paired with a `<wa-tooltip>`. Do not use a `<div>` or `<span>` as the trigger — only native button elements receive keyboard focus by default.
- Associate the tooltip content with the related input using `aria-describedby` on the input element, not only on the button. This ensures screen readers announce the help text when the user focuses the field.
- The `wa-tooltip` component respects `prefers-reduced-motion`. When motion is reduced, the tooltip appears immediately without a fade transition.
- Set `trigger='focus hover'` on `wa-tooltip` so keyboard and pointer users both receive the tooltip. Never use `trigger='click'` only — this excludes pointer users who rely on hover.
- Tooltip text must be a static string. Do not inject async content into an open tooltip — this causes unexpected announcements in screen readers.
- When the TooltipButton appears inside a `<label>` element, clicking the label will also activate the button. Wrap the button in a `<span>` with `onclick` propagation stopped, or place the button outside the label element to avoid double-activation.
- The 44x44px touch target is achieved via padding on the button. Do not reduce padding on mobile breakpoints to fit tighter layouts — use a layout adjustment instead.
Keyboard interaction
| Key | Action |
|---|---|
| Tab | Moves focus to the trigger button. Tooltip appears immediately. |
| Shift+Tab | Moves focus away from the trigger button. Tooltip is dismissed. |
| Enter | No action — the button has no click behaviour. Tooltip is already visible from focus. |
| Space | No action — same as Enter for this component. |
| Escape | Dismisses the tooltip while the trigger retains focus. |
Why it matters
Government digital services must meet WCAG 2.1 AA. Many stakeholders and community members using Open Point and Social Point rely on screen readers or keyboard navigation due to disability or assistive technology policy. If the help content in a TooltipButton is inaccessible, those users are denied the same contextual support available to pointer users — a compliance risk and a service equity issue.
Focus
Focus ring is 3px solid, colour --op-color-interactive-focus, with a 2px transparent offset to ensure visibility on both light and dark backgrounds.
Focus must never be trapped inside the tooltip panel — the panel contains only static text.
When the tooltip is dismissed via Escape, focus remains on the trigger button (not returned to a previous element).
Do not suppress the focus ring under any circumstances, including when outline: none is applied globally.
ARIA
| Role or attribute | When to use | Example |
|---|---|---|
aria-label | Applied to the trigger button. Provides an accessible name since the button has no visible text label. | <button aria-label="Help: Submission window"> |
aria-describedby | Applied to the associated input element, referencing the tooltip content container's ID. Ensures screen readers announce the help text when the input receives focus. | <input aria-describedby="tooltip-submission-window" /> |
role="tooltip" | Applied to the tooltip panel element. Identifies the container as tooltip content to assistive technology. | <div role="tooltip" id="tooltip-submission-window">Submissions close at midnight on the last business day of the quarter.</div> |
aria-hidden | Applied to the decorative icon inside the trigger button so screen readers don't announce the icon glyph name. | <wa-icon name="question-circle" aria-hidden="true"></wa-icon> |
Contrast
Tooltip text (--op-color-text-inverse) on tooltip background (--op-color-bg-inverse): must meet 4.5:1 for normal text. Verify with your theme's resolved values. Trigger icon (--op-color-text-secondary) on page background (--op-color-bg-primary): must meet 3:1 for UI components (WCAG 1.4.11 Non-text Contrast). Trigger icon at hover/focus (--op-color-interactive-hover): must meet 3:1 against --op-color-bg-primary. Do not rely on colour alone to distinguish the trigger from surrounding text — the circular button shape and icon provide additional differentiation.
Touch targets
The visual icon is 24px but the interactive touch target must be at least 44x44px, achieved via padding or a transparent hit-area extension. Verify this on mobile breakpoints — do not reduce padding to accommodate tight label rows.
Things to avoid
- Do not place interactive elements (links, buttons, inputs) inside the tooltip panel. Tooltips are not dialogs — focus does not move into them.
- Do not use colour alone to signal that the tooltip is open. The tooltip panel's visibility is the primary indicator.
- Do not auto-dismiss the tooltip on a timer. Users with cognitive disabilities or slow reading speeds must have unlimited time to read tooltip content (WCAG 2.2.1).
- Do not use a `title` attribute as a fallback — it is not keyboard accessible and behaves inconsistently across browsers and assistive technologies.