Tooltip — a hint that appears on hover or focus. The tooltip closes when the cursor is moved away, focus is removed, the page is scrolled, or Esc is pressed.

Width

The tooltip size is determined by its content, but the component width cannot exceed 300px.

Sometimes it's more convenient if the text in the tooltip doesn't wrap and is displayed on a single line. For example, when comparing checksums, outputting email addresses, or file and folder paths. For such cases, don't limit the tooltip width.

Style

Arrow

Add a pointer arrow when it can be confusing which element the hint relates to.

Positioning

Relative to Element

In normal circumstances, the tooltip opens at the top centered. The position near the trigger element can be adjusted manually.

Choose a position where the tooltip won't cover content that the user will interact with next. For example, in a vertical list, open tooltips to the side so the hint doesn't interfere with viewing the neighboring element in the reading direction.

Position Priority

If there isn't enough space to display the tooltip, it will open on the opposite side. The kbqPlacementPriority attribute helps configure fallback positions if they need to differ from the default order.

Near the Cursor

When configuring kbqRelativeToPointer="true", the tooltip is positioned relative to the cursor. This is often needed for long strings (checksums, email, paths) so the hint appears right at the cursor.

Near the Caret

The tooltip can open next to the text caret in an editable field. Its position updates as the user types, moves the caret or scrolls the field. When text is selected, the tooltip anchors to the selection.

Set kbqRelativeToCaret="true" to enable this mode. Use kbqRelativeToCaretVertical to control the tooltip's vertical position: field places it above or below the whole field, while line places it next to the line containing the caret. By default, auto uses field for a single-line input and line for a textarea and contenteditable. Horizontally, the tooltip follows the caret in both modes. All tooltip placements remain available.

If the browser cannot determine the caret's position, the tooltip anchors to the field. This may happen with password, email and number inputs, right-to-left text, or centered and right-aligned text. When the tooltip is attached to a container, it uses the first editable element inside it.

Offset

Delay

When hovering over an element, the tooltip appears with a 0.4 second delay and disappears instantly.

When switching focus or hovering over another element with a tooltip, the delay works as follows:

• The first tooltip appears with standard delay,
• Subsequent tooltips appear instantly,
• If the previous element's tooltip has disappeared and more than 2 seconds have passed, the 0.4 second delay applies again.

Moving the Cursor onto the Tooltip

The tooltip receives pointer events, so moving the cursor from the trigger onto the tooltip itself does not close it. This matters for users who read at high magnification, where the pointer often ends up over the tooltip, and for tooltips that take a while to read (WCAG 1.4.13 "Content on Hover or Focus"). Combine it with [hideWithTimeout]="true" and kbqLeaveDelay to give the cursor time to travel to the tooltip — see the Interactive Tooltip example.

Set [ignoreTooltipPointerEvents]="true" for the opposite behavior: the tooltip becomes transparent to the pointer and clicks pass through to whatever is underneath it. Use it for tooltips that float over other click targets — for example the overflow hints of a scrolling option list, where a pointer-capturing tooltip would swallow the click that selects the neighboring option.

Before v20 the tooltip ignored pointer events by default, so this reverses on upgrade: markup that relied on clicks passing through now has to ask for it. The built-in overflow hints (kbq-title, kbqEllipsisCenter, the option and timezone-option hints) already opt out on their own, and so does any tooltip whose kbqTrigger is manual or none — hovering such a pane neither keeps it open nor closes it, so there is nothing for a pointer-capturing pane to protect.

Only One Tooltip at a Time

At most one tooltip is on screen: showing a new one closes the previously opened tooltip. The rule applies to tooltips opened by hover, focus, click or keydown — including the kbq-title and kbqEllipsisCenter hints.

Tooltips driven programmatically (kbqTrigger="manual") stay out of the rule: they neither close other tooltips nor get closed. Validation hints work this way.

To opt a single tooltip out, use [kbqTooltipSingleInstance]="false"; to change the default for the whole application, provide the KBQ_TOOLTIP_SINGLE_INSTANCE_DEFAULT token:

providers: [{ provide: KBQ_TOOLTIP_SINGLE_INSTANCE_DEFAULT, useValue: false }];

Usage Examples

Tooltip for Disabled Button

If a certain button or function is unavailable, the tooltip can explain why.

Custom Hints

For special cases, you can change the tooltip dimensions and place more than just text inside it. Use the Contrast-fade style, which is similar to the application background, to ensure content contrast against the tooltip background.

Recommendations

• If you need to use interactive elements (buttons, links, etc.) inside the tooltip, use Popover instead.
• The Tooltip component is always preferable to the system one. Don't use both methods simultaneously in the same interface.
• For tooltips to work effectively, it's important to keep them brief and clear. Long explanations can be difficult to read and distracting, so it's best to avoid them.
• The tooltip height depends on the content. The recommended maximum height is 480px (may be increased at the designer's discretion).