Tooltip

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

2 samples
1
2
3
4
5
6
<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>
v3.0.3

Best practices

Below are important guidelines on using the Tooltip component.

Correct Tooltip directional
Do use directional props based on the placement of the item generating the Tooltip.
Avoid Tooltip directional
Avoid using directional props that could make the Tooltip fall off of the interface.

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

KeyFunction
TabMoves 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 ShiftMoves 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

Correct Tooltip content length
Do use Tooltips as brief text helpers. Prefer brevity.
Avoid Tooltip content length
Avoid using Tooltips with more than one sentence or 75 characters. Prefer Popover or Modal for more content.
Correct Tooltip helpful
Do use actionable verbiage when applicable.
Avoid Tooltip not helpful
Avoid being vague or baiting with Tooltips.
Correct Tooltip punctuation
Do put helpful statements in Tooltips.
Avoid Tooltip punctuation
Avoid having questions in Tooltips.
Correct Tooltip add
Do use Tooltips to properly describe a contextual problem.
Avoid Tooltip add
Avoid redundancy with Tooltips.
  • 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

PropertyAttributeDescriptionTypeDefault
closeOnClickclose-on-clickCloses the component when the referenceElement is clicked.booleanfalse
labellabel
deprecatedNo longer necessary. Overrides the context of the component's description, which could confuse assistive technology users.
Accessible name for the component.
string
offsetDistanceoffset-distanceOffset the position of the component away from the referenceElement.number6
offsetSkiddingoffset-skiddingOffset the position of the component along the referenceElement.number0
openopenWhen true, the component is open.booleanfalse
overlayPositioningoverlay-positioningDetermines 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"
placementplacementDetermines 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"
referenceElementreference-elementThe 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

NameDescription
default (unnamed)A slot for adding text.

Styles

NameDescription
--calcite-tooltip-background-colorSpecifies the component's background color.
--calcite-tooltip-border-colorSpecifies the component's border color.
--calcite-tooltip-corner-radiusSpecifies the component's corner radius.
--calcite-tooltip-text-colorSpecifies the component's text color.
--calcite-tooltip-z-indexSpecifies the z-index value for the component.

Events

NameDescriptionBehavior
calciteTooltipBeforeCloseFires when the component is requested to be closed and before the closing transition begins.bubblescomposed
calciteTooltipBeforeOpenFires when the component is added to the DOM but not rendered, and before the opening transition begins.bubblescomposed
calciteTooltipCloseFires when the component is closed and animation is complete.bubblescomposed
calciteTooltipOpenFires when the component is open and animation is complete.bubblescomposed

Methods

NameDescriptionSignature
componentOnReadyCreate a promise that resolves once component is fully loaded.componentOnReady(): Promise<void>
repositionUpdates the position of the component.reposition(delayed?: boolean): Promise<void>

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close