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.
FigmaStorybookDocs
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.
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.
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.
