Tooltip

This documentation is currently being revised and is in beta status. Content may still change.

This component is being retested for accessibility. The full test is still pending and can only be completed after a release.

Synonyms: Inline dialog, popover

Description: The Tooltip component shows contextual information when users hover over or focus a reference element. It acts as the visual counterpart of an aria label and is intended only for sighted users without screen reader support. The component is primarily an internal KoliBri component and is marked as deprecated.

The Tooltip component is used internally in KoliBri and is only truly accessible when a reference element points to the tooltip. It is not intended for direct use in application development.

The component is marked as deprecated in the source code and is planned for removal in a future major release.

Example

The tooltip is displayed when the reference element is hovered or focused:

<div style="display: flex; gap: 1rem;">
 <button aria-label="Home page">
 <kol-icon _icon="codicon codicon-home"></kol-icon>
 <kol-tooltip>Go to the home page</kol-tooltip>
 </button>
</div>

Accessibility

• Hidden from screen readers: The tooltip text is hidden from screen readers via aria-hidden. The accessible name must already be present on the reference element.
• Sighted users only: The tooltip is a visual supplement and must not replace meaningful labels or announcements.
• Not keyboard-focusable itself: The tooltip content is not directly reachable with the keyboard, but appears together with focus on the reference element.
• Accessibility testing: Tooltips can be ignored in testing as long as the same information is exposed by the reference element for assistive technology.

From an accessibility testing perspective, tooltips can be ignored as long as development also ensures that the tooltip text is conveyed by the reference element for screen reader users.

Links and references

Usage

Keyboard interaction

Key	Function
Escape	Closes the tooltip so overlaid page information becomes visible again.
Tab	Focuses the reference element; the tooltip is then displayed.

Best practices

• Keep text short: Tooltips should contain only a few words or one short sentence.
• Use a block-capable reference element: The reference element must not use display: inline; use block, inline-block, flex, grid, or a similar layout context.
• Provide an accessible name: The reference element must already have an aria label or equivalent accessible naming.
• Do not put critical information in tooltips: Important legal, security, or workflow-relevant information must remain visible to all users.
• Stay consistent: Consistent placement, timing, and visual style improve usability.

Use cases

• Icon buttons with an additional visible label
• Contextual hints next to form fields
• Supplemental explanations for compact UI elements
• Quick orientation hints on hover

FAQ

Can I use a tooltip for information that all users must perceive?
No. Use a component such as kol-popover-button or another accessible disclosure pattern instead.

Does the reference element need to be present on the client?
Yes. The tooltip is positioned relative to its reference element in the DOM.

Can I place HTML content inside the tooltip?
Yes, via the slot, but keep the content minimal. Tooltips are meant for short, simple text.

Construction / Technical

Playground

Example of tooltip usage inside button elements:

<div style="display: flex; gap: 1rem;">
 <button aria-label="Open settings">
 <kol-icon _icon="codicon codicon-settings"></kol-icon>
 <kol-tooltip>Settings</kol-tooltip>
 </button>
 <button aria-label="Show help">
 <kol-icon _icon="codicon codicon-info"></kol-icon>
 <kol-tooltip>Help</kol-tooltip>
 </button>
</div>

Features with code

Configure width

Tooltip width normally follows its content. To configure the width, define a CSS custom property on the surrounding container:

<div style="--kol-tooltip-width: 15rem;">
 <button aria-label="Description">
 <kol-icon _icon="codicon codicon-info"></kol-icon>
 <kol-tooltip>This is a longer tooltip text that wraps across multiple lines when space is limited.</kol-tooltip>
 </button>
</div>

Different reference elements

The tooltip works with different kinds of reference elements:

<!-- With a button -->
<button aria-label="Button with tooltip">
 Button text
 <kol-tooltip>Tooltip text</kol-tooltip>
</button>

<!-- With a link -->
<a href="#" aria-label="Link with tooltip" style="display: inline-block;">
 Link
 <kol-tooltip>Link tooltip</kol-tooltip>
</a>

<!-- With a custom element -->
<div role="button" aria-label="Div with tooltip" style="display: inline-block; cursor: pointer;">
 Interactive element
 <kol-tooltip>Element tooltip</kol-tooltip>
</div>

Known issues and workarounds

CSS contain: layout can break positioning

When CSS contain: layout is used within or on the tooltip element, positioning may become incorrect. This is a documented in .

Workaround: Do not apply contain: layout directly to the tooltip. Use it only where it is needed for container queries.

Outlook: In the long term, the native could replace floating-ui. At the moment it is only available in Chrome, so floating-ui is still required for Firefox and Safari.

Inline display on the reference element

The reference element must not use display: inline. Use at least display: inline-block or another block-like layout context, otherwise the tooltip cannot be positioned correctly.