Tooltip

Tooltip specification

• Tooltip specification
  • Owned By
    • Signed off by
    • Revision history
  • Overview
    • Acceptance criteria
  • User stories
    • End-user stories
    • Developer stories
  • Functionality
    • End-user experience
    • Developer experience
      • Anchor target
      • Previous element target
      • Text content with message property
    • Behaviors
    • Localization
    • Keyboard interactions
  • API
    • IgcTooltipComponent
      • Properties
      • Methods
      • Events
      • Slots
      • CSS Shadow Parts
  • Test scenarios
    • Automation
      • Rendering and initialization
      • Attributes and properties
      • Behaviors
  • Accessibility
    • ARIA
      • IgcTooltipComponent intrinsic ARIA properties
      • References
    • RTL
  • Assumptions and limitations

Owned By

Team Name: Astrea + Design and Web Development

Developer name: Arkan Ahmedov, Riva Ivanova

Designer name: Diana Koleva, Dilyana Yarabanova

Signed off by

• Radoslav Karaivanov | Date:
• Radoslav Mirchev | Date:
• Svilen Dimchevski | Date:

Revision history

Version	Author	Date	Notes
1	Riva Ivanova	2025-03-17	Initial draft - user stories, API, test scenarios
1.1	Riva Ivanova	2025-03-20	Updated draft specification
1.2	Riva Ivanova	2025-04-02	Finalized specification
1.3	Riva Ivanova	2025-04-07	Updated API, ARIA and test scenarios
1.4	Arkan Ahmedov	2025-04-14	Updated API and ARIA

Overview

The igc-tooltip component provides us with a way to display a tooltip for a specific element. A tooltip is a popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it. It typically appears after a small delay and disappears when Escape is pressed or on mouse leave.

Acceptance criteria

The igc-tooltip must:

• support user-provided slotted content.
• expose a way to set an element instance or an IDREF as the anchor for the tooltip.
• expose a way to show/hide the tooltip manually.
• be WAI-ARIA compliant.

User stories

End-user stories

As an end-user, I expect to be able to:

• display a tooltip for an element when hovering with the mouse or focusing with the Tab key.
• hide the tooltip of an element when no longer hovering it with the mouse.
• interact with the content of the tooltip.

Developer stories

As a developer, I expect to be able to:

• display a tooltip for a specific element when hovered with the mouse or focused with the Tab key.
• hide the tooltip of a specific element when no longer interacting with it.
• manually show/hide the tooltip for a specific element without interacting with it.
• specify the delay time of a tooltip before it is shown.
• specify the delay time of a tooltip before it is hidden.
• specify the position at which the tooltip should be displayed.
• use a default template for the content of the tooltip with the ability to style it.
• provide a custom template for the content of the tooltip.
• enable/disable the tooltip from showing/hiding.

Functionality

End-user experience

Design Hand-off

Developer experience

Anchor target

Target is specified by providing an IDREF.

<igc-tooltip anchor="hover-button">
  Congrats you've hovered the button!
</igc-tooltip>

<igc-button id="hover-button">Hover me</igc-button>

Target is specified by providing an Element.

<igc-tooltip id="tooltip">
  Congrats you've hovered the button!
</igc-tooltip>

<igc-button id="hover-button">Hover me</igc-button>

constructor() {
  const anchor = document.querySelector('#hover-button') as IgcButtonComponent;
  const tooltip = document.querySelector('#tooltip') as IgcTooltipComponent;
  tooltip.anchor = anchor;
}

Previous element target

If no anchor is provided, the tooltip will consider the first preceding sibling that is an element as the target.

<igc-button>Hover me</igc-button>
<igc-tooltip>
  Congrats you've hovered the button!
</igc-tooltip>

<p>
  Here is some text with a
  <strong>element</strong>
  <igc-tooltip>😎</igc-tooltip>
  that has a tooltip.
</p>

Text content with message property

Text content can be provided via the message property.

<igc-button>Hover me</igc-button>
<igc-tooltip message="Congrats you've hovered the button!">
</igc-tooltip>

Slotted content takes priority over the message property.

<igc-button>Hover me</igc-button>
<igc-tooltip message="I will be hidden.">
  I will be shown!
</igc-tooltip>

Behaviors

• If the tooltip is invoked when a pointing cursor moves over the target element, then it remains open as long as the cursor is over the target or the tooltip.
• When focusing the target via Tab key, the focus stays on the target element while the tooltip is displayed.
• If the tooltip is invoked when the trigger element receives focus, then it is dismissed when it no longer has focus (onBlur).
• The tooltip cannot be focused. Its elements could not be focused as well. The elements within a tooltip are not focusable but the user can interact with them.
• On initial open state, the tooltip does not close automatically after the number of milliseconds specified by hideDelay. The tooltip will remain open until interacting with it or its target.
• When the tooltip is set as sticky:
  • It renders a default close button (X).
  • It can be closed only by clicking the close button or pressing the Esc key.

Localization

No specific implementation is needed.

Keyboard interactions

Key	Behavior
Escape	Dismisses the tooltip.

API

IgcTooltipComponent

Properties

Property	Attribute	Reflected	Type	Default	Description
open	open	Yes	boolean	false	Whether the tooltip is shown.
disableArrow	disable-arrow	Yes	boolean	false	Whether to disable the rendering of the arrow indicator for the tooltip.
inline	inline	Yes	boolean	false	Improves positioning for inline based elements, such as links.
offset	offset	No	number	6	The offset of the tooltip from the anchor in pixels.
placement	placement	No	IgcPlacement	top	Where to place the floating element relative to the parent anchor element.
anchor	anchor	No	string | Element	-	An element instance or an IDREF to use as the anchor for the tooltip.
showTriggers	show-triggers	No	string	pointerenter	Which event triggers will show the tooltip. Expects a comma separate string of different event triggers.
hideTriggers	hide-triggers	No	string	pointerleave click	Which event triggers will hide the tooltip. Expects a comma separate string of different event triggers.
showDelay	show-delay	No	number	200	Specifies the number of milliseconds that should pass before showing the tooltip.
hideDelay	hide-delay	No	number	300	Specifies the number of milliseconds that should pass before hiding the tooltip.
message	message	No	string	-	Specifies a plain text as tooltip content.
sticky	sticky	No	boolean	false	Specifies if the tooltip remains visible until the user closes it via the close button or Esc key.

Methods

Name	Type signature	Description
show	(): Promise<boolean>	Shows the tooltip if not already shown.
hide	(): Promise<boolean>	Hides the tooltip if not already hidden.
toggle	(): Promise<boolean>	Toggles between shown/hidden state.

Events

Name	Cancellable	Description	Parameters
igcOpening	Yes	Emitted before the tooltip is shown.	{ target: Element }
igcOpened	No	Emitted after the tooltip is shown.	{ target: Element }
igcClosing	Yes	Emitted before the tooltip is hidden.	{ target: Element }
igcClosed	No	Emitted after the tooltip is hidden.	{ target: Element }

Slots

Name	Description
(default)	Default slot for the tooltip content.
close-button	Renders tooltip close button in sticky mode.

CSS Shadow Parts

Part	Description

Test scenarios

Automation

Rendering and initialization

• passes the default WAI-ARIA automation.
• is initialized without errors.
• is initialized with the appropriate default state.
• should correctly slot user-provided content for the tooltip.
• the tooltip is initially hidden.

Attributes and properties

• should show/hide the tooltip based on showDelay and hideDelay.
• should show/hide the tooltip based on the open property.
• should determine the tooltip's current state via the open property.
• should set target via anchor propety by providing an IDREF.
• should set target via anchor propety by providing an Element.
• should show/hide the arrow via the disableArrow property.
• should show/hide the arrow via the disable-arrow attribute.
• should show the tooltip via show() method.
• should hide the tooltip via hide() method.
• should toggle between shown/hidden state via toggle() method.
• should change the show/hide trigger via showTriggers/hideTriggers property.
• should change the show/hide trigger via show-triggers/hide-triggers attribute.
• should render a default close button when in sticky mode.
• hide triggers should not close the tooltip when in sticky mode.
• should close the tooltip when in sticky mode by clicking the default close button.
• should close the tooltip when in sticky mode by pressing the Esc key.
• should provide content via the message property.
• slotted content takes priority over the message property.

Behaviors

• it should be shown when hovering over its target and hidden when the mouse leaves.
• it should be shown when focusing its target via Tab key and hidden when losing focus (on blur).
• it should be hidden when pressing Escape.
• events are correctly emitted on user interaction.
• events can be canceled.

Accessibility

ARIA

IgcTooltipComponent intrinsic ARIA properties

role:

• tooltip by default
• status when the sticky property is true

inert: updated depending on whether the tooltip is visible or not

aria-atomic: true

aria-live: polite

---

References

https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/

https://www.w3.org/TR/wai-aria-1.2/#tooltip

RTL

The component should work in a Right-To-Left context without additional setup or configuration.

Assumptions and limitations

None applicable.