Tooltips are small text-based components that when triggered by a reference element provide context to the user.
Overview
Tooltips float over other elements in the z-axis and provide text to quickly assist the user to understand context, actions, and other elements. A Tooltip can be a helpful UX device to give the user clarity before committing to an action. Avoid relying heavily on Tooltips, as you should prefer headers and labels that accurately describe a workflow. Tooltip positioning can be automatic or manually set to avoid clipping in the interface.
It is recommended to place Tooltips shallowly in the DOM.
To support interactive content, consider Popover.
For more advanced floating workflows, refer to Dialog.
Usage
- General helper text
- Succinct action hints
Sample
<div>
<calcite-link id="tooltip-button">Data disclaimer</calcite-link>
<calcite-tooltip reference-element="tooltip-button">
<span>This data was collected over a 24 hour period</span>
</calcite-tooltip>
</div>
Best practices
Below are important guidelines on using the Tooltip component.

Accessibility
It is strongly recommended to house the component's content in an element, such as a span
or p
, providing context to assistive technologies when accessed.
Keyboard navigation
Key | Function |
---|---|
Tab | Moves focus to access the component's contents from its reference element. If the current focus is the reference element, focus will leave the element. |
Tab and Shift | Moves focus to access the component's contents from its reference element. If the current focus is the reference element, focus will leave the element. |
Writing and copy



- Tooltip text should be succinct and straight to the point
- Periods are not necessary for ending Tooltip text
- Avoid contractions such as "you're", "aren't", "don't", and "can't" to avoid confusion and to assist with internationalization
- For longer content, please consider Popover
- Recommended character maximum: 75
API reference
Properties
Property | Attribute | Description | Type | Default |
---|---|---|---|---|
closeOnClick | close-on-click | Closes the component when the referenceElement is clicked. | boolean | false |
label | label | string | ||
offsetDistance | offset-distance | Offset the position of the component away from the referenceElement . | number | 6 |
offsetSkidding | offset-skidding | Offset the position of the component along the referenceElement . | number | 0 |
open | open | When true , the component is open. | boolean | false |
overlayPositioning | overlay-positioning | Determines the type of positioning to use for the overlaid content.
Using "absolute" will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout.
The "fixed" value should be used to escape an overflowing parent container, or when the reference element's position CSS property is "fixed" . | "absolute" | "fixed" | "absolute" |
placement | placement | Determines where the component will be positioned relative to the referenceElement . | "auto" | "auto-end" | "auto-start" | "bottom" | "bottom-end" | "bottom-start" | "leading" | "leading-end" | "leading-start" | "left" | "left-end" | "left-start" | "right" | "right-end" | "right-start" | "top" | "top-end" | "top-start" | "trailing" | "trailing-end" | "trailing-start" | "auto" |
referenceElement | reference-element | The referenceElement to position the component according to its "placement" value.
Setting to the HTMLElement is preferred so the component does not need to query the DOM for the referenceElement .
However, a string ID of the reference element can be used. | Element | VirtualElement | string |
Slots
Name | Description |
---|---|
default (unnamed) | A slot for adding text. |
Styles
Name | Description |
---|---|
--calcite-tooltip-background-color | Specifies the component's background color. |
--calcite-tooltip-border-color | Specifies the component's border color. |
--calcite-tooltip-corner-radius | Specifies the component's corner radius. |
--calcite-tooltip-text-color | Specifies the component's text color. |
--calcite-tooltip-z-index | Specifies the z-index value for the component. |
Events
Name | Description | Behavior |
---|---|---|
calciteTooltipBeforeClose | Fires when the component is requested to be closed and before the closing transition begins. | |
calciteTooltipBeforeOpen | Fires when the component is added to the DOM but not rendered, and before the opening transition begins. | |
calciteTooltipClose | Fires when the component is closed and animation is complete. | |
calciteTooltipOpen | Fires when the component is open and animation is complete. |
Methods
Name | Description | Signature |
---|---|---|
componentOnReady | Create a promise that resolves once component is fully loaded. | componentOnReady(): Promise<void> |
reposition | Updates the position of the component. | reposition(delayed?: boolean): Promise<void> |