Tooltip

Tooltips appear on hover, focus, or touch, and disappear after blur, mouse and touch leave, and click - including the keyboard handlers. On click, tooltips exit immediately.

Tooltip with similar behaviour can be found in:

• macOS push button
• Google Apps on Web (Calendar, Mail)
• Chrome
• Spotify
• HTML element title

Example

Basic Usage

Placements

Internally, Tooltip reexposes placement API from Tip component.

Variants

By default, Coral Tooltip uses dark background. You can pass TooltipVariants.Light to variant prop to make it light.

Open and Close Delay

Tooltip’s open and close events can be delayed by setting openDelay and closeDelay props. By default, openDelay is 100ms and closeDelay is 200ms, but these can be adjusted through the props.

Tooltip Warmup & Cooldown

By default, Tooltip has a warmup & cooldown mechanism. Here’s how it works:

Warmup: When the page loads, tooltips are initially “cold” and won’t show immediately on hover. The first tooltip hover triggers a “warmup” period before the tooltip appears. After the tooltip is warmed up, the next tooltip hover will be shown immediately without delay.

Cooldown: After any tooltip is closed, there’s a 500ms grace period where tooltips remain “warm” and show immediately on hover. If no tooltip is hovered within this period, tooltips go into “cooldown” mode and require the warmup delay again.

This prevents accidental tooltip spam while maintaining responsive behavior once users start interacting with tooltips.

These mechanism will be affected by the openDelay and closeDelay. The warmup duration will use the tooltip’s openDelay value, while the cooldown period will take the maximum of the default duration (500ms) and the tooltip’s closeDelay value.

You can isolate a tooltip from the global warmup and cooldown mechanism by setting the isolated prop to true. This is useful when you want a tooltip to behave independently without affecting or being affected by other tooltips on the page.

LabelTooltip

LabelTooltip is a specialized wrapper for Tooltip components, primarily designed for labelling IconButton component.

LabelTooltip has several key characteristics that make it ideal for icon button labelling: it displays without an arrow indicator, contains non-hoverable tooltip content, uses a default open delay of 500ms and close delay of 100ms, and is specifically optimized for icon button labelling scenarios.

Nest Tooltip

Important: Tooltips cannot be nested. This is a fundamental limitation of the tooltip system to prevent UI conflicts and ensure proper user experience.

Additionally, tooltips cannot be used inside the title prop of another tooltip.

Custom Events

Unlike Ant Design’s Popovers, this Tooltip does not provide special prop trigger, because it’s rather unnecessary and too specific.

Alternatively, any events triggering the tooltip can be defaultPrevented, controlled fully or partially based on onActiveChange callback.

Controlled

If you control it into hover only events, note that it might have accessibility issue because keyboard users won’t be able to see it.

Using .preventDefault()

You can also use uncontrolled way. But, this is less recommended because you will need to understand and have more couplings between the internal state changes and your app. Prop initialActive is also supported.

Tooltip with Balloon

Using Tooltip with Balloon on an element is not very straightforward. This is a tradeoff with the ease of use of each individually. However, here’s a way to get around the implementation using forwardRef:

Custom child rendering

To make Tooltip component compatible with various kinds of child elements, you might need to customize the props passed to child element, renderChild will give you the flexibility to do so. You are encouraged to use cloneElement to return the child element.

Relevant components

• Tip

References

• WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/
• Reach-UI: https://reacttraining.com/reach-ui/tooltip/
• Material Design: https://material.io/components/tooltips/#usage

API

LabelTooltip

Tooltip