CivicTheme
  • Docs
  • Changelog
  • Getting started
    • Introduction
    • Installation
    • Getting help
    • Security policy
    • Partnerships
  • Installation
    • Drupal theme
  • Contributing
    • Contribution model
    • Contribution basics
    • Small contribution spec
    • Medium contribution spec
    • Major (RFC-level) contribution spec
    • Code of conduct
    • Figma contributions
  • Components
    • Component list
    • Atoms
      • Button
      • Chip
      • Content link
      • Check box
      • Field description
      • Field message
      • Fieldset
      • Label
      • Radio
      • Select
      • Textarea
      • Text field
      • Heading
      • Link
      • Paragraph
      • Popover
      • Quote
      • Table
      • Tag
      • Text list
    • Molecules
      • Accordion
      • Attachment
      • Breadcrumb
      • Callout
      • Event Card
      • Field
      • Figure
      • Group filter
      • Logo
      • Map
      • Navigation card
      • Next step
      • Pagination
      • Promo card
      • Search
      • Service card
      • Single filter
      • Snippet
      • Subject Card
      • Table of Contents
      • Tabs
      • Tag List
      • Tooltip
      • Video Player
    • Organisms
      • Alert
      • Banner
      • Campaign
      • Footer
      • Header
      • List
      • Message
      • Mobile Navigation
      • Navigation
      • Promo
      • Side Navigation
      • Skip link
      • Slider
      • Social links
  • Content Authoring
    • Overview
    • Global settings
      • Favicon
      • Header
        • Site slogan
        • Header logos
        • Primary navigation
        • Secondary navigation
      • Banner
      • Search
      • Link
      • Skip link
      • Side navigation
      • Signup
      • Footer
        • Footer logo
        • Social links
        • Footer navigation
        • Acknowledgement of Country
        • Copyright
      • Colours
    • Content types
      • Page
        • Configure the banner
      • Event
      • Alert
    • Content components
      • Accordion
      • Automated list
      • Attachment
      • Callout
      • Campaign
      • Content
        • Quote
      • iFrame
      • Manual List
        • Event card
        • Event reference card
        • Navigation card
        • Navigation reference card
        • Promo card
        • Promo reference card
        • Publication card
        • Service card
        • Subject card
        • Subject reference card
        • Snippet
      • Map
      • Next step
      • Promo
      • Slider
      • Webform
    • Vocabularies
      • Topics
      • Site sections
    • User accounts & roles
Powered by GitBook
On this page
  • When to use
  • When not to use
  • Best practice guidelines
  • Variations
  • Accessibility
  • Security
  • Sites using this component
  • Component inspiration and uplift
  • Research on this component
  • Known issues
  • More research needed
  • Help improve this component
  • Resources
  • References
  • Changelog
  • Contact us

Was this helpful?

Edit on GitHub
Export as PDF
  1. Components
  2. Molecules

Tooltip

A tooltip provides contextual information or explanatory text when users hover over, focus on, or tap an element.

When to use

Use tooltips when:

  • You need to provide additional information about UI elements that may not be immediately obvious to users

  • You want to explain the purpose of an icon, button, or interactive element without cluttering the interface

  • You need to provide clarification for abbreviated content or complex terminology

  • You need to offer guidance without taking users away from their current task

When not to use

Do not use tooltips when:

  • The information is essential for users to complete a task (use visible text instead)

  • The content requires user interaction (use modals or other interactive elements instead)

  • The information is lengthy (use expandable sections or documentation links instead)

  • The element is used frequently, as repeated tooltip appearances can become annoying

  • The target element is too small to easily hover over or activate (especially on touch devices)

  • Critical error messages or warnings need to be displayed (use alerts or validation messages instead)


Best practice guidelines

  • Simplicity: Keep tooltip content brief, focused, and to the point. Aim for 1-2 short sentences.

  • Positioning: Position tooltips consistently and ensure they don't obscure important content or extend outside viewports. The tooltip should appear close to the trigger element.

  • Timing: Implement appropriate timing for showing and hiding tooltips. Tooltips should appear promptly on hover (around 300ms delay) and remain visible for a reasonable duration.

  • Accessibility: Ensure tooltips are keyboard accessible and available to screen reader users. Use ARIA attributes appropriately.

  • Visibility: Make tooltips visually distinct from surrounding content with sufficient contrast and clear boundaries.

  • Behaviour: Tooltips should disappear when the user moves away from the triggering element or when keyboard focus changes.

  • Content: Use tooltips for helpful information, not for essential content. If information is required to complete a task, it should be visible without requiring hover.

  • Consistency: Maintain consistent design, positioning, and behaviour of tooltips throughout the interface.

Variations

Position variations:

  • Top: The tooltip appears above the trigger element

  • Right: The tooltip appears to the right of the trigger element

  • Bottom: The tooltip appears below the trigger element

  • Left: The tooltip appears to the left of the trigger element


Accessibility

Based on the CivicTheme v1.7.0 Accessibility Assessments file, there is no specific accessibility assessment for the tooltip component. However, the closely related component "Popover" has been assessed and may share similar accessibility considerations.

For tooltips to be fully accessible, they should:

  • Be accessible via keyboard navigation

  • Be announced properly by screen readers using appropriate ARIA attributes

  • Have sufficient colour contrast

  • Not rely solely on hover for activation (should also work with keyboard focus)

  • Remain visible long enough for users to read the content

Security

No specific security concerns are associated with the tooltip component as it is primarily a UI presentation element. However, ensure that sensitive information is not inadvertently displayed in tooltips as they may be visible to anyone viewing the screen.

Sites using this component

No specific CivicTheme sites using this component are currently documented.

Component inspiration and uplift

The Tooltip component in CivicTheme is not directly modelled after a specific component in the former Australian Government Design System (AGDS) as stated in the CivicTheme Compliance Statements. According to the document, "Unlike all other components in CivicTheme that have been modelled after, or influenced by, a specific component in the Australian Design System, the tooltip has not."

CivicTheme's tooltip component was created as a purposeful UI element designed to help users understand features when they can't immediately comprehend them from the interface alone. The documentation notes that "tooltips are available for tasks that users need to accomplish on your site."


Research on this component

UX Score: ★★☆☆☆

Confidence rating = Low (Minimal evidence available)

No specific user research data is available for this component in the provided documentation. The assessment is based on general tooltip usability principles and not on dedicated CivicTheme user testing.

In general, tooltips are well-established UI patterns that most users understand. However, they present challenges on mobile devices and for users with motor control difficulties who may struggle to hover precisely over small elements.

Known issues

  • Mobile usability: Tooltips rely on hover interactions which don't translate well to touch interfaces. Mobile implementations need careful consideration of trigger mechanisms.

  • Timing challenges: Setting appropriate delays for tooltip appearance and disappearance can be challenging - too quick and they become distracting, too slow and they feel unresponsive.

  • Positioning complexities: Tooltips may appear off-screen or be cut off when triggered near viewport edges, requiring smart positioning logic.

  • Keyboard accessibility: Some tooltip implementations may not be fully accessible to keyboard-only users if they're designed exclusively for mouse hover interactions.

More research needed

More user research is needed in the following areas:

  • Mobile and touch device interaction patterns for tooltips

  • User preferences for tooltip timing, positioning, and styling

  • Effectiveness of tooltips for different user groups, including those with visual or cognitive impairments

  • How tooltips integrate with and complement other contextual help mechanisms in interfaces

  • Optimal tooltip content length and formatting for different use cases

Help improve this component

To help make this component useful and up-to-date, you can:

  • Contribute to our tooltip component discussion

  • Submit your user research findings to help improve the tooltip component

  • Propose a change to the tooltip component


Resources

  • Storybook

  • GitHub

References

  • Harley, A. (2014). Hover Effects and Tooltips: User Experience Insights. Nielsen Norman Group.

Changelog

Version
Date
Changes

1.7.0

March 2024

Component documented

Contact us

PreviousTag ListNextVideo Player

Last updated 1 month ago

Was this helpful?

Check out our to learn more.

If you have a question about the CivicTheme design system or need our help, visit the page for guidance.

contributing section
Figma
Nielsen Norman Group. (2020). Tooltip Guidelines
W3C. (2023). ARIA: tooltip role
Getting Help