Popover and tooltip API improvements

[gfellerph]

Discussed in #4513

^{Originally posted by gfellerph January 23, 2025}
Tooltips and popovers are a much discussed topic.

• [components]: Tooltip refactoring #4170
• Tooltip & popover visibility #4455
• Z-index guidelines #4407
• [bug]: post-popovercontainer promotes to Top Layer, causing UI overlap issues #4398
• Add optional safe triangle to <post-popovercontainer> #4169
• post-tooltip improvements #3823
• Popovercontainer: emit close event after animation #3204

This is a proposal to define a more flexible API and clean up some issues that have arisen after the first implementations have been used in the real world.

Distinction

Tooltip

A means of displaying a description or extra information about an element, usually on hover, but can also be on click or tap.¹

Semantically, tooltips are linked to the trigger element through aria-describedby so the tooltip text is automatically being read by screenreaders when focus is on the trigger.

Popover

An element that pops up from another element over other content; it differs from a tooltip in that it is usually triggered via click instead of hover and can contain interactive elements.²

Semantically, popovers act as disclosure content which is not linked to the trigger. The trigger has an aria-expanded attribute to communicate the current state of the popover.

Issues with the current implementations

• Hoverable tooltips get in the way of the cursor when there are a lot of buttons in a table. To resolve this issue, a delay option was added with Tooltip: add delay option #3213. The delay resolves the issue in most cases and is compatible with recommendations from Accessibility experts like Sarah Higley (https://sarahmhigley.com/writing/tooltips-in-wcag-21/#best-practices-summary). Still, it feels like a workaround and not a real solution to the issue at hand
• Customers request large content to be shown on hover ([bug]: Tooltips add shadow on optional arrow #4290). A tooltip is semantically incorrect in this case but the popover does not show up on hover
• Devs reported difficulties with setting id attributes for all the things. An alternative attribute has been proposed to get around the side effects of id, but was dismissed as the uniqueness is wanted here ([components]: Tooltip refactoring #4170)
• ng-bootstrap popovers provide a way to be opened on hover which is missing from our implementation (https://ng-bootstrap.github.io/#/components/popover/examples#autoclose

Tooltip proposal

Design: https://www.figma.com/design/JIT5AdGYqv6bDRpfBPV8XR/Foundations-%26-Components-Next-Level?node-id=21-180&m=dev

Behaviour

• Opens on interest (hover, focus, long-press)
• Closes on interest-lost on either the trigger or the tooltip itself (unless no-hover is set), enabling users to interact with the tooltip, for example highlighting text for copy/paste or translation
• Implements light-dismiss, closing on escape keypress or outside click and also closes when another tooltip is opened (default functionality of the popover attribute)

Tooltip props

• arrow, boolean prop that will display an arrow, false by default (because that's what boolean props should be)
• delay, [open-delay]|[open-delay close-delay] if it's a number, open delay in milliseconds, if it's a string of two numbers, e.g. delay="200 400", the first number is the open delay and the second the close delay, defaults to undefined
• placement, string, one of the floating ui placement possibilities, defaults to 'top'
• no-hover, boolean that defaults to false. Can be used to hide the tooltip when the cursor leaves the trigger, making the tooltip not hoverable. This is not accessible, but a requested feature that would be worked around if not there
• id, string used to connect <post-tooltip-trigger> with the target <post-tooltip>, optional if the tooltip is nested inside the trigger (only triggers the first found tooltip)

Background colour can be set by palette utilities.

Tooltip trigger props

• for, string connects the trigger to it's tooltip, optional if the tooltip is nested inside the trigger

Tooltip content

A tooltip should contain a descriptive text for the action of it's trigger element, e.g. a button used for toggling bold text should have a tooltip containing the text "Bold". The text should be short and descriptive as it's being read by screenreaders by default. A tooltip can serve as a replacement of the accessible name of an icon button.

Interactive elements are not allowed in tooltips, use a popover with trigger-action="interest".

Setup

<!-- Tooltip is connected via for/id attributes -->
<post-tooltip-trigger for="bold-description">
  <button>B</button>
</post-tooltip-trigger>
<post-tooltip id="bold-description">Bold</post-tooltip>

<!-- Tooltip is nested inside the trigger, no for/id attributes necessary -->
<post-tooltip-trigger>
  <button>B</button>
  <post-tooltip>Bold</post-tooltip>
</post-tooltip-trigger>

Popover proposal

Design: https://www.figma.com/design/JIT5AdGYqv6bDRpfBPV8XR/Foundations-%26-Components-Next-Level?node-id=21-173&m=dev

Behaviour

• Opens according to it's trigger-on prop or on click by default
• Closes based on trigger action or on light dismiss
• Does not open in modal mode (not supported by the popover attribute anyways)

Popover props

• id, string used to connect <post-popover-trigger> with the target <post-popover>, optional if the popover is nested inside the trigger (only triggers the first found popover)
• placement, string, one of the floating ui placement possibilities, defaults to 'top'
• arrow, boolean, show an arrow, false by default
• delay, [open-delay]|[open-delay close-delay] if it's a number, open delay in milliseconds, if it's a string of two numbers, e.g. delay="200 400", the first number is the open delay and the second the close delay, defaults to undefined (intended to be used together with trigger-on="interest"

Popover trigger props

• for, string connects the trigger to it's popover, optional if the tooltip is nested inside the trigger
• trigger-on, click|interest|manual specifies what action triggers the popover.
  • click, the default option open/closes the popover on click
  • interest, the popover opens on hover, long-press and focus
  • manual, the popover does not open or close but the trigger wires up all accessibility behaviour. It's expected that the user adds own logic for toggling the popover
• trigger-action, toggle|show|hide specifies if the trigger toggles a popover on repeated actions, only opens or only closes it

Background colour can be set by palette utilities.

Popover content

Popovers support a broader array of content elements and can provide additional context and contain interactive elements.

Setup

<!-- Popover is connected via for/id attributes -->
<post-popover-trigger for="more-info">
  <button>show info</button>
</post-popover-trigger>
<post-popover id="more-info">
  <h3>Additional info</h3>
  <p>Lorem...</p>
  <a href="/goto">Read more about it</a>
</post-popover>

<!-- Popover is nested inside the trigger, no for/id attributes necessary -->
<post-popover-trigger>
  <button>show info</button>
  <post-popover>
    <h3>Additional info</h3>
    <p>Lorem...</p>
    <a href="/goto">Read more about it</a>
  </post-popover>
</post-tooltip-trigger>

Footnotes

1. https://component.gallery/components/tooltip/ ↩

2. https://component.gallery/components/popover/

↩