Tooltip

A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.

Features

  • Opens when the trigger is focused or hovered
  • Closes when the trigger is activated or with escape
  • Custom delay for opening and closing
  • Supports custom positioning

Anatomy

  • Trigger: The element that triggers the tooltip popover
  • Content: The tooltip's content container
  • Arrow: An optional arrow component

API Reference

createTooltip

The builder function used to create the tooltip component.

Props

Prop Default Type / Description
positioning position: 'top'

A configuration object which determines how the floating element is positioned relative to the trigger.

arrowSize 8
number

The size of the arrow which points to the trigger in pixels.

closeOnEscape true
boolean

Whether or not to close the tooltip when the escape key is pressed.

forceVisible false
boolean

Whether or not to force the tooltip to always be visible. This is useful for custom transitions and animations using conditional blocks.

portal body
string | HTMLElement | null

The element or selector to render the tooltip into. Nested floating elements are automatically rendered into their parent if not specified. Pass in null to disable portalling.

closeOnPointerDown true
boolean

Whether the tooltip closes when the pointer is down.

openDelay 1000
number

The delay in milliseconds before the tooltip opens after a pointer over event.

closeDelay 500
number

The delay in milliseconds before the tooltip closes after a pointer leave event.

disableHoverableContent false
boolean

Prevents the tooltip content element from remaining open when hovered. If true, the tooltip will only be open when hovering the trigger element.

group -
string | boolean

If set to true, whenever you open this tooltip, all other tooltips with group also set to true will close. If you pass in a string instead, only tooltips with the same group value will be closed.

defaultOpen false
boolean

Whether the tooltip is open by default or not.

open -
Writable<boolean>

A writable store that controls whether or not the tooltip is open.

See Bring Your Own Store

onOpenChange -
ChangeFn<boolean>

A callback called when the value of the open store should be changed.

See Change Functions

ids -
Record<'trigger' | 'content', string>

Override the internally generated ids for the elements.

Elements

Element Description

The builder store used to create the tooltip trigger.

The builder store used to create the tooltip content.

The builder store used to create the tooltip arrow.

States

State Description
open

A writable store that indicates whether the tooltip is open or not

Options

Option Description
positioning

A configuration object which determines how the floating element is positioned relative to the trigger.

arrowSize

The size of the arrow which points to the trigger in pixels.

closeOnEscape

Whether or not to close the tooltip when the escape key is pressed.

forceVisible

Whether or not to force the tooltip to always be visible. This is useful for custom transitions and animations using conditional blocks.

portal

The element or selector to render the tooltip into. Nested floating elements are automatically rendered into their parent if not specified. Pass in null to disable portalling.

closeOnPointerDown

Whether the tooltip closes when the pointer is down.

openDelay

The delay in milliseconds before the tooltip opens after a pointer over event.

closeDelay

The delay in milliseconds before the tooltip closes after a pointer leave event.

disableHoverableContent

Prevents the tooltip content element from remaining open when hovered. If true, the tooltip will only be open when hovering the trigger element.

group

If set to true, whenever you open this tooltip, all other tooltips with group also set to true will close. If you pass in a string instead, only tooltips with the same group value will be closed.

IDs

Option Description
trigger

The writable store that represents the id of the trigger element.

content

The writable store that represents the id of the content element.

trigger

The tooltip trigger element.

Data Attributes

Data Attribute Value
[data-state]

'open' | 'closed'

[data-melt-tooltip-trigger]

Present on all tooltip trigger elements.

Custom Events

Event Value
m-pointerdown (e: ) => void
m-pointerenter (e: ) => void
m-pointerleave (e: ) => void
m-focus (e: ) => void
m-blur (e: ) => void
m-keydown (e: ) => void

content

The tooltip content element.

Data Attributes

Data Attribute Value
[data-state]

'open' | 'closed'

[data-melt-tooltip-content]

Present on all tooltip content elements.

Custom Events

Event Value
m-pointerenter (e: ) => void
m-pointerdown (e: ) => void

arrow

The tooltip arrow element.

Data Attributes

Data Attribute Value
[data-arrow]

'true'

[data-melt-tooltip-arrow]

Present on all tooltip arrow elements.

Accessibility

Adheres to the WAI-ARIA tooltip role design pattern

Tooltips are only activated on hover or on focus, and not on press. Since the tooltip is generally used to describe an action, its usefulness would be limited in case it appeared on press, seeing as the action would have already been performed. This behaviour is also predicted by the WAI-ARIA tooltip role design pattern.

Chances are if you have a need to display content on press, using a tooltip isn't accessible/appropriate, and should instead consider using a Popover .

Key Behavior
Tab

Opens/closes the tooltip without delay.

Space

If open, closes the tooltip without delay.

Enter

If open, closes the tooltip without delay.

Esc

If open, closes the tooltip without delay.