Tooltip Specification

1. Overview

The igxTooltipTarget and the igxTooltip directives provide us with a way to display a tooltip for a specific element.

Tooltip with a simple text

<button [igxTooltipTarget]="tooltipRef">Hover me</button>

<span #tooltipRef="tooltip" igxTooltip>Hello there, I am a tooltip!</span>

2. User Stories

As a developer, I want to:

be able to display a tooltip for a specific element when hovered with the mouse.
be able to hide the tooltip of a specific element when no longer hovering it with the mouse.
be able to manually show the a tooltip for a specific element without interacting with the mouse (for example hovering the element).
be able to manually hide the tooltip of a specific element without interacting with the mouse.
be able to specify the delay time of a tooltip before it gets shown.
be able to specify the delay time of a tooltip before it gets hidden.
be able to specify the position at which the tooltip should be displayed.
be able to specify if the tooltip should automatically open on hover of the element.
be able to specify if the tooltip should automatically close when no longer hovering the element.
be able to use a default template for the content of the tooltip with the ability to style it.
be able to provide a custom template for the content of the tooltip.
be able to enable/disable the tooltip from showing.
be able to configure a sticky mode where the end-user has to interact with the tooltip element in order to dismiss it.
be able to change the default close icon in sticky mode.

As an end user, I want to:

be able to display a tooltip for an element when hovering with the mouse.
be able to hide the tooltip of an element when no longer hovering it with the mouse.
be able to interact with the content of the tooltip.
be able to dismiss any tooltip by pressing Escape regardless of its configuration parameters.

3. API

IgxTooltipDirective Properties

Name	Type	Description
context	any	Specifies the context of the tooltip. (Used to store and access any tooltip related data.)

Since the IgxTooltip directive extends the IgxToggle directive and there is no specific functionality it adds apart from some styling classes and attributes in combination with the properties from above, you can refer to the IgxToggle README for additional details.

IgxTooltipTargetDirective Properties

Name	Type	Default	Description
showDelay	number	200	Specifies the number of milliseconds that should pass before showing the tooltip.
hideDelay	number	300	Specifies the number of milliseconds that should pass before hiding the tooltip.
tooltipDisabled	boolean	false	Specifies if the tooltip should not show when hovering its target with the mouse.
tooltipHidden	boolean	-	Indicates if the tooltip is currently hidden.
nativeElement	any	-	Reference to the native element of the directive.
tooltip	any	-	Allows specifying a plain text tooltip without adding a DOM element.
hasArrow	boolean	false	Whether to enable the rendering of the arrow indicator of the component.
sticky	boolean	false	Specifies if the tooltip remains visible until the user closes it via the close button or `Esc` key.
closeTemplate	TemplateRef	-	Allows templating the default close icon `x`.
positionSettings	PositionSettings	-	Controls the position and animation settings used by the tooltip.

IgxTooltipTargetDirective Methods

Name	Type	Arguments	Description
showTooltip	void	N/A	Shows the tooltip.
hideTooltip	void	N/A	Hides the tooltip.

IgxTooltipTargetDirective Events

Name	Description	Cancelable	Event arguments
tooltipShow	Emitted when the tooltip starts showing. (This event is fired before the start of the countdown to showing the tooltip.)	True	ITooltipShowEventArgs
tooltipHide	Emitted when the tooltip starts hiding. (This event is fired before the start of the countdown to hiding the tooltip.)	True	ITooltipHideEventArgs

4. Keyboard Interaction

Key	Behavior
`Escape`	Pressing `Escape` on a active page will close the last shown tooltip

5. Behaviors

The tooltip will try to respect its given position settings. In scenarios where the tooltip content may be clipped (viewport edge), it will try to reposition itself automatically.
In sticky mode:
- A shown tooltip will ignore the default hover in/out behavior when the user interacts with the tooltip.
- Dismissing the tooltip is achieved by clicking on the default close button, pressing Escape, or programmatically.
Any custom content added via the closeButton template is rendered only when the tooltip is in sticky mode.
The showDelay/hideDelay values affect only end-user interactions. Showing a tooltip through the API ignores them.
Clicking on the target before the tooltip is shown will prevent it from showing.

6. Test Scenarios

Automation

The values of the IgxTooltipTargetDirective inputs can be changed.
The tooltip is initially hidden.
The tooltip is opened when hovering its target and is hidden when unhovering its target.
The default position of the tooltip is bottom-center in relation to its target.
The tooltip is not opened when it is disabled and hovering its target.
The mouseenter and mouseleave interactions respect the showDelay and the hideDelay values.
The tooltip is opened when opening it through the API and is hidden when closing it through the API.
The opening and closing methods from the API do NOT respect the showDelay and the hideDelay values.
The tooltip closes and reopens if it was opened through API and then its target is hovered.
The tooltip closes and reopens if opening it through API multiple times.
The tooltip respects the passed overlay settings
The tooltip emits tooltipShow and tooltipHide events accordingly.
The tooltip emits tooltipShow and tooltipHide events with the correct event arguments.
The tooltipShow and tooltipHide events can be successfully cancelled.
The tooltip closes when pressing the 'Escape' key.

Manual

Test the behavior of the tooltip with various overlaySettings.

7. Limitations

The IgxTooltipTarget uses the TooltipPositionStrategy to position the tooltip and arrow element. If a custom position strategy is used (overlaySettings.positionStrategy) and hasArrow is set to true, the custom strategy should extend the TooltipPositionStrategy. Otherwise, the arrow will not be displayed.

The arrow element is positioned based on the provided position settings. If the directions and starting points do not correspond to any of the predefined position values, the arrow is positioned in the top middle side of the tooltip (default tooltip position bottom).

Predefined position values

Position	Horizontal Direction	Horizontal Start Point	Vertical Direction	Vertical Start Point
top	HorizontalAlignment.Center	HorizontalAlignment.Center	VerticalAlignment.Top	VerticalAlignment.Top
top-start	HorizontalAlignment.Right	HorizontalAlignment.Left	VerticalAlignment.Top	VerticalAlignment.Top
top-end	HorizontalAlignment.Left	HorizontalAlignment.Right	VerticalAlignment.Top	VerticalAlignment.Top
bottom	HorizontalAlignment.Center	HorizontalAlignment.Center	VerticalAlignment.Bottom	VerticalAlignment.Bottom
bottom-start	HorizontalAlignment.Right	HorizontalAlignment.Left	VerticalAlignment.Bottom	VerticalAlignment.Bottom
bottom-end	HorizontalAlignment.Left	HorizontalAlignment.Right	VerticalAlignment.Bottom	VerticalAlignment.Bottom
right	HorizontalAlignment.Right	HorizontalAlignment.Right	VerticalAlignment.Middle	VerticalAlignment.Middle
right-start	HorizontalAlignment.Right	HorizontalAlignment.Right	VerticalAlignment.Bottom	VerticalAlignment.Top
right-end	HorizontalAlignment.Right	HorizontalAlignment.Right	VerticalAlignment.Top	VerticalAlignment.Bottom
left	HorizontalAlignment.Left	HorizontalAlignment.Left	VerticalAlignment.Middle	VerticalAlignment.Middle
left-start	HorizontalAlignment.Left	HorizontalAlignment.Left	VerticalAlignment.Bottom	VerticalAlignment.Top
left-end	HorizontalAlignment.Left	HorizontalAlignment.Left	VerticalAlignment.Top	VerticalAlignment.Bottom

Customizing the arrow's position

The arrow's position can be customized by overriding the positionArrow(arrow: HTMLElement, arrowFit: ArrowFit) method.

For example:

export class CustomStrategy extends TooltipPositioningStrategy {
    constructor(settings?: PositionSettings) {
        super(settings);
    }

    public override positionArrow(arrow: HTMLElement, arrowFit: ArrowFit): void {
        Object.assign(arrow.style, {
            left: '-0.25rem',
            transform: 'rotate(-45deg)',
            [arrowFit.direction]: '-0.25rem',
        });
    }
}

public overlaySettings: OverlaySettings = {
    positionStrategy: new CustomStrategy({
        horizontalDirection: HorizontalAlignment.Right,
        horizontalStartPoint: HorizontalAlignment.Right,
        verticalDirection: VerticalAlignment.Bottom,
        verticalStartPoint: VerticalAlignment.Bottom,
    })
};

<igx-icon [igxTooltipTarget]="tooltipRef" [hasArrow]="true" [overlaySettings]="overlaySettings">
    info
</igx-icon>

<span #tooltipRef="tooltip" igxTooltip>
    Hello there, I am a tooltip!
</span>