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.
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 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.
    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 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-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.