Tooltip

A popup that appears when an element is hovered or focused, showing a hint for sighted users.

<ui:tooltip.root>
    <ui:tooltip.trigger asChild="{true}">
        <ui:button>Hover me</ui:button>
    </ui:tooltip.trigger>
    <ui:tooltip.content>This is the tooltip content.</ui:tooltip.content>
</ui:tooltip.root>

Features

Opens on hover and focus
Closes on pointer down or Escape key press
Supports custom open and close delays
Supports custom positioning with placement options
Automatically adjusts position to stay in viewport

Anatomy

<primitives:tooltip.root>
    <primitives:tooltip.trigger />
    <primitives:tooltip.positioner>
        <primitives:tooltip.content>
            <primitives:tooltip.arrow />
        </primitives:tooltip.content>
    </primitives:tooltip.positioner>
</primitives:tooltip.root>

Installation

typo3 ui:add tooltip

Read more about installing Components and Primitives.

Examples

Change the placement

Pass placement through the positioning prop. The tooltip below opens to the right of its trigger.

<ui:tooltip.root positioning="{placement: 'right'}">
    <ui:tooltip.trigger asChild="{true}">
        <ui:button>Hover for right tooltip</ui:button>
    </ui:tooltip.trigger>
    <ui:tooltip.content>I appear on the right!</ui:tooltip.content>
</ui:tooltip.root>

Delay the opening

Set openDelay in milliseconds, the default is 400. The tooltip below appears one second after you hover the button.

<ui:tooltip.root openDelay="1000">
    <ui:tooltip.trigger asChild="{true}">
        <ui:button>Slow tooltip (1000ms)</ui:button>
    </ui:tooltip.trigger>
    <ui:tooltip.content>I took 1000ms to appear.</ui:tooltip.content>
</ui:tooltip.root>

Delay the closing

Set closeDelay in milliseconds, the default is 150. The tooltip below stays visible for 500 ms after the pointer leaves.

<ui:tooltip.root closeDelay="500">
    <ui:tooltip.trigger asChild="{true}">
        <ui:button>Lingers for 500ms</ui:button>
    </ui:tooltip.trigger>
    <ui:tooltip.content>I stay visible for 500ms after you leave.</ui:tooltip.content>
</ui:tooltip.root>

Set disabled to keep the tooltip closed, for example while the action behind a button is unavailable.

<ui:tooltip.root disabled="{true}">
    <ui:tooltip.trigger asChild="{true}">
        <ui:button>No tooltip here</ui:button>
    </ui:tooltip.trigger>
    <ui:tooltip.content>You won't see this.</ui:tooltip.content>
</ui:tooltip.root>

Label an icon button

Give an icon-only button a tooltip for sighted visitors and a visually hidden label for screen readers.

<ui:tooltip.root>
    <ui:tooltip.trigger asChild="{true}">
        <ui:button variant="ghost" size="icon">
            <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4">
                <path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z"></path>
                <circle cx="12" cy="12" r="3"></circle>
            </svg>
            <span class="sr-only">Settings</span>
        </ui:button>
    </ui:tooltip.trigger>
    <ui:tooltip.content>Settings</ui:tooltip.content>
</ui:tooltip.root>

API Reference

The following tables cover the available props of the Fluid Primitives. For a full list of available client side props and methods, see the Zag.js Machine API.

tooltip.root

Provides tooltip state and context for the composed parts. Renders no wrapper element.

Name	Description	Required	Default
`defaultOpen`	`boolean` The initial open state of the tooltip when rendered. Use when you don't need to control the open state of the tooltip.	No	false
`disabled`	`boolean` Whether the tooltip is disabled.	No	false
`openDelay`	`integer` The open delay of the tooltip.	No	400
`closeDelay`	`integer` The close delay of the tooltip.	No	150
`closeOnPointerDown`	`boolean` Whether to close the tooltip on pointerdown.	No	true
`closeOnEscape`	`boolean` Whether to close the tooltip when the Escape key is pressed.	No	true
`closeOnScroll`	`boolean` Whether the tooltip should close on scroll.	No	true
`closeOnClick`	`boolean` Whether the tooltip should close on click.	No	true
`interactive`	`boolean` Whether the tooltip's content is interactive and remains open when hovered.	No	false
`positioning`	`array` The user provided options used to position the popover content.	No	-
`rootId`	`string` The root ID of the component, used for hydration and identification.	No	-
`ids`	`array` The IDs of of the component parts for composition.	No	[]
`autoMount`	`boolean` Whether the client initializes the component on its own. Set it to false to mount it yourself with `mount()`	No	true

tooltip.trigger

Acts as the anchor that opens the tooltip. Renders a <button> element.

Name	Description	Required	Default
`value`	`string`	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-tooltip-trigger`	<uid>
`data-value`	The value of the item
`data-current`	Present when current
`data-expanded`	Present when expanded
`data-state`	"open" \| "closed"

tooltip.positioner

Positions the tooltip content relative to the trigger. Renders a <div> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

tooltip.content

Displays the tooltip bubble content. Renders a <div> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-tooltip-content`	<uid>
`data-state`	"open" \| "closed"
`data-instant`
`data-placement`	The placement of the content
`data-side`	The side of the trigger that the content is positioned on

tooltip.arrow

Displays a decorative tooltip arrow. Renders a <div> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Machine JavaScript API

Name	Type	Description
`open`	`boolean`	Whether the tooltip is open.
`setOpen`	`(open: boolean) => void`	Function to open the tooltip.
`triggerValue`	`string \| null`	The trigger value
`setTriggerValue`	`(value: string \| null) => void`	Function to set the trigger value
`reposition`	`(options?: Partial<PositioningOptions>) => void`	Function to reposition the popover
`getTriggerState`	`(props?: TriggerProps) => TriggerState`	Returns the state of a specific trigger, including whether it's the currently active one
`getContentState`	`() => ContentState`	Returns the state of the content

Accessibility

Key	Description
`Tab`	Opens/closes the tooltip without delay.
`Escape`	If open, closes the tooltip without delay.

Tooltip

Features

Anatomy

Installation

Examples

Change the placement

Delay the opening

Delay the closing

Disable the tooltip

Label an icon button

API Reference

tooltip.root

tooltip.trigger

Rendered data attributes

tooltip.positioner

tooltip.content

Rendered data attributes

tooltip.arrow

Machine JavaScript API

Accessibility