Tooltip

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

View code

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.
`escapeBehavior`	`'close'`	`'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore'` Defines how the tooltip reacts when the Escape key is pressed. `close`: Closes the tooltip immediately. `ignore`: Prevents the tooltip from closing and also blocks the parent element from closing in response to the Escape key. `defer-otherwise-close`: Delegates the action to the parent element. If no parent is found, it closes the element. `defer-otherwise-ignore`: Delegates the action to the parent element. If no parent is found, nothing is done.
`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 own portal if not specified. Pass in `null` to disable portalling. Pass in `undefined` to use parent portal.
`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
`trigger`	The builder store used to create the tooltip trigger.
`content`	The builder store used to create the tooltip content.
`arrow`	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.
`escapeBehavior`	Defines how the tooltip reacts when the Escape key is pressed. `close`: Closes the tooltip immediately. `ignore`: Prevents the tooltip from closing and also blocks the parent element from closing in response to the Escape key. `defer-otherwise-close`: Delegates the action to the parent element. If no parent is found, it closes the element. `defer-otherwise-ignore`: Delegates the action to the parent element. If no parent is found, nothing is done.
`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 own portal if not specified. Pass in `null` to disable portalling. Pass in `undefined` to use parent portal.
`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-side]`	'top' \| 'right' \| 'bottom' \| 'left'
`[data-align]`	'start' \| 'center' \| 'end'
`[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-side]`	'top' \| 'right' \| 'bottom' \| 'left'
`[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.

On This Page