Tooltip
newIt looks like you're hovering over a button. Would you like help? A short hint about a control, shown on hover, keyboard focus or a long press.
Installation
Put one TooltipProvider around the app. Tooltips under it share their settings and warm up together: once one opens, the next opens instantly as you move along a toolbar.
<script setup lang="ts">
import { TooltipProvider } from '@/components/ui/tooltip'
</script>
<template>
<TooltipProvider>
<RouterView />
</TooltipProvider>
</template>
No provider? Tooltips still work, just without the shared warm-up.
Usage
<script setup lang="ts">
import { Button } from '@/components/ui/button'
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
</script>
<template>
<Tooltip>
<TooltipTrigger as-child>
<Button variant="outline">Hover</Button>
</TooltipTrigger>
<TooltipContent>Add to library</TooltipContent>
</Tooltip>
</template>
It opens when the pointer rests on the trigger for delay milliseconds, 600 by default. Moving the pointer restarts the wait, so sweeping across a toolbar opens nothing. Keyboard focus opens it instantly (focus from a click doesn't), and so does a long press on touch screens.
It closes when the pointer or focus leaves, on a press, on Escape, or when the trigger scrolls. Only one tooltip is open at a time.
A tooltip is just a hint: clicks go right through it. Need something to hover, select or click? Use a Hover Card or a Popover. Or set hoverable to keep the tooltip open while the pointer moves onto it.
Examples
Icon buttons
If the tooltip is the button's name, put the same text in the button's aria-label and set role="label" on the tooltip. Screen readers then read the name once, not twice.
Keyboard shortcut
A Kbd inside a tooltip takes the tooltip's colours.
Disabled button
A disabled button ignores the pointer and can't take focus, so its tooltip never opens. Use aria-disabled="true" on a Button instead: it looks the same and ignores clicks and keys, but the tooltip can still explain why it's off.
Side and arrow
side and align on TooltipContent place the tooltip, and it flips and shifts to stay on screen. Add a TooltipArrow inside to point at the trigger.
Follow the cursor
follow-cursor keeps the tooltip at the pointer: along x, y or both. Opened by touch or the keyboard, it stays on the trigger.
Directive
For a plain text hint, one attribute is enough. Import v-tooltip where you use it, or register it once with app.directive('tooltip', vTooltip):
<script setup lang="ts">
import { Button } from '@/components/ui/button'
import { vTooltip } from '@/components/ui/tooltip'
</script>
<template>
<Button v-tooltip="'Save changes'">Save</Button>
</template>
| Form | Meaning |
|---|---|
v-tooltip="'Save'" | The text. An empty string, false, null or undefined shows nothing. |
v-tooltip:bottom | The side: top, right, bottom or left. |
v-tooltip.label | For icon buttons: adds aria-label with the text if the element has no name of its own. |
v-tooltip="{ content, side, delay, followCursor, … }" | The text plus any Tooltip prop and the placement props of TooltipContent: side, align, sideOffset, alignOffset, avoidCollisions, collisionPadding, sticky, hideWhenDetached. |
Everything else works the same as with the parts. For rich content, a Kbd or an arrow, use the parts.
The directive doesn't reach Toggle, ToggleGroupItem or ToolbarToggleItem. Reka's Toggle renders a hidden form input next to the button, so the component has no single root element, and Vue drops a runtime directive on it without a trace in production. Wrap those in the parts instead:
<Tooltip>
<TooltipTrigger as-child>
<ToggleGroupItem value="bold" aria-label="Bold"><Bold /></ToggleGroupItem>
</TooltipTrigger>
<TooltipContent>Bold</TooltipContent>
</Tooltip>
Touch
No hover on touch screens, so a tooltip opens on a long press: hold still on the trigger for touchDelay milliseconds, 500 by default. It stays for touchHideDelay milliseconds after you lift your finger, 1500 by default, or until you tap elsewhere.
The press doesn't select text, open the context menu or click the trigger. A shorter tap is just a click. Opened by touch, the tooltip gets data-touch and draws a bit larger.
touch sets the policy:
| Value | Behaviour |
|---|---|
auto | The default. A long press, except where the browser has its own: links, images, text fields, draggable elements and context menu targets. Add data-kappa-longpress to an element to put it on that list. |
long-press | A long press everywhere. |
off | Touch never opens it. |
Open and close reasons
update:open gets { reason, event } as a second argument:
<Tooltip @update:open="(open, { reason }) => console.log(open, reason)">
| Reason | When |
|---|---|
trigger-hover | The pointer rested on the trigger, or left it. |
trigger-focus | The trigger got keyboard focus, or lost it. |
trigger-press | A long press opened it, or a press on the trigger closed it. |
touch-release | touchHideDelay passed after the finger lifted. |
outside-press | A press outside the trigger and the tooltip. |
escape-key | Escape. |
scroll | Something holding the trigger scrolled. |
sibling-open | Another tooltip opened. This one closes without its exit animation (data-instant). |
disabled | The tooltip or its trigger got disabled, or the trigger element was replaced. |
Changes through v-model:open emit nothing.
API Reference
TooltipContent and TooltipArrow take a class that merges with their own.
TooltipProvider
| Prop | Default | Type and description |
|---|---|---|
| delay | — | numberMilliseconds the pointer rests on a trigger before its tooltip opens. Moving the pointer restarts the wait. 600 by default. |
| skipDelay | — | numberMilliseconds after a tooltip closes during which the next one opens at once. 300 by default. |
| restThreshold | — | numberSquared distance in pixels a pointer move has to reach to restart the wait; smaller jitter does not. 2 by default. |
| touch | — | TouchPolicyHow touch opens a tooltip: |
| touchDelay | — | numberMilliseconds a finger holds the trigger before the tooltip opens. 500 by default. |
| touchHideDelay | — | numberMilliseconds a tooltip opened by touch stays after the finger lifts. 1500 by default. |
| hoverable | — | booleanKeeps a tooltip open while the pointer moves from the trigger onto it, and lets it take pointer events. |
| closeOnClick | — | booleanCloses a tooltip when its trigger is pressed. On by default. |
| disabled | — | booleanKeeps every tooltip under the provider from opening. |
| Slot | Scope and description |
|---|---|
| default | {}The app, or the part of it whose tooltips share these settings and warm up together. |
Tooltip
| Prop | Default | Type and description |
|---|---|---|
| open | — | booleanWhether it is open, bound with |
| defaultOpen | — | booleanWhether it starts open when |
| role | — | TooltipRole
|
| followCursor | — | TooltipFollowCursorKeeps the tooltip at the pointer along |
| delay | — | numberThis tooltip's own |
| restThreshold | — | numberThis tooltip's own |
| touch | — | TouchPolicyThis tooltip's own |
| touchDelay | — | numberThis tooltip's own |
| touchHideDelay | — | numberThis tooltip's own |
| hoverable | — | booleanKeeps the tooltip open while the pointer moves onto it, and lets it take pointer events. |
| closeOnClick | — | booleanCloses the tooltip when its trigger is pressed. |
| disabled | — | booleanKeeps the tooltip from opening, and closes it when open. |
| Event | Payload and description |
|---|---|
| update:open | [open: boolean, details: TooltipOpenChangeDetails]Fires when it opens or closes, with |
| Slot | Scope and description |
|---|---|
| default | { open: boolean; }The trigger and the content. Receives |
TooltipTrigger
| Prop | Default | Type and description |
|---|---|---|
| reference | — | ReferenceElementA virtual element to place the tooltip against instead of the trigger. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. A button by default. |
| Slot | Scope and description |
|---|---|
| default | {}The trigger's content, or with |
TooltipContent
| Prop | Default | Type and description |
|---|---|---|
| forceMount | — | booleanKeeps the tooltip mounted while closed, for animating it with a JavaScript library. |
| ariaLabel | — | stringThe text screen readers read as the trigger's description, instead of the tooltip's text as it was when it opened. Bind it when the text changes while open. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| side | — | "top" | "right" | "bottom" | "left"The side of the trigger to open on. Flips to the other side when there is no room, unless |
| sideOffset | 4 | numberDistance in pixels from the trigger. |
| align | — | "start" | "center" | "end"Alignment against the trigger along the chosen side. |
| alignOffset | — | numberOffset in pixels from the |
| avoidCollisions | — | booleanKeeps the tooltip inside the collision boundary by flipping and shifting it. |
| collisionBoundary | — | Element | (Element | null)[] | nullThe element or elements used as the collision boundary. The viewport by default. |
| collisionPadding | 8 | number | Partial<Record<"top" | "right" | "bottom" | "left", number>>Distance in pixels from the boundary edges where collisions start. |
| arrowPadding | — | numberPadding between an arrow and the tooltip's corners. |
| sticky | — | "partial" | "always"
|
| hideWhenDetached | — | booleanHides the tooltip when the trigger is scrolled out of view. |
| positionStrategy | — | "absolute" | "fixed"The CSS position used to place the tooltip. |
| updatePositionStrategy | — | "always" | "optimized"
|
| Event | Payload and description |
|---|---|
| escapeKeyDown | [event: KeyboardEvent]Fires on Escape. Call |
| pointerDownOutside | [event: Event]Fires on a pointer press outside. Call |
| Slot | Scope and description |
|---|---|
| default | {}The tooltip's text, and an optional |
TooltipArrow
| Prop | Default | Type and description |
|---|---|---|
| width | — | numberWidth of the arrow in pixels. |
| height | — | numberHeight of the arrow in pixels. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. An SVG by default. |
Props
- delay
numberMilliseconds the pointer rests on a trigger before its tooltip opens. Moving the pointer restarts the wait. 600 by default.- skipDelay
numberMilliseconds after a tooltip closes during which the next one opens at once. 300 by default.- restThreshold
numberSquared distance in pixels a pointer move has to reach to restart the wait; smaller jitter does not. 2 by default.- touch
TouchPolicyHow touch opens a tooltip:auto(a long press, except on links, images, text fields, draggable elements and context menu triggers),long-pressoroff.autoby default.- touchDelay
numberMilliseconds a finger holds the trigger before the tooltip opens. 500 by default.- touchHideDelay
numberMilliseconds a tooltip opened by touch stays after the finger lifts. 1500 by default.- hoverable
booleanKeeps a tooltip open while the pointer moves from the trigger onto it, and lets it take pointer events.- closeOnClick
booleanCloses a tooltip when its trigger is pressed. On by default.- disabled
booleanKeeps every tooltip under the provider from opening.
Slots
- default
{}The app, or the part of it whose tooltips share these settings and warm up together.
Props
- open
booleanWhether it is open, bound withv-model:open.- defaultOpen
booleanWhether it starts open whenv-model:openis not used.- role
TooltipRoledescriptionmakes the tooltip the trigger's accessible description.labelis for a tooltip that repeats the trigger's own name, such as an icon button'saria-label: the description is left out so screen readers do not read the name twice.- followCursor
TooltipFollowCursorKeeps the tooltip at the pointer alongx,yorbothaxes while it moves over the trigger;noneby default. Opened by touch or the keyboard, it stays on the trigger.bothturnshoverableoff.- delay
numberThis tooltip's owndelay, over the provider's.- restThreshold
numberThis tooltip's ownrestThreshold, over the provider's.- touch
TouchPolicyThis tooltip's owntouchpolicy, over the provider's.- touchDelay
numberThis tooltip's owntouchDelay, over the provider's.- touchHideDelay
numberThis tooltip's owntouchHideDelay, over the provider's.- hoverable
booleanKeeps the tooltip open while the pointer moves onto it, and lets it take pointer events.- closeOnClick
booleanCloses the tooltip when its trigger is pressed.- disabled
booleanKeeps the tooltip from opening, and closes it when open.
Emits
- update:open
[open: boolean, details: TooltipOpenChangeDetails]Fires when it opens or closes, with{ reason, event }as the second argument.
Slots
- default
{ open: boolean; }The trigger and the content. Receivesopen.
Props
- reference
ReferenceElementA virtual element to place the tooltip against instead of the trigger.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render. A button by default.
Slots
- default
{}The trigger's content, or withas-childthe element that becomes the trigger.
Props
- forceMount
booleanKeeps the tooltip mounted while closed, for animating it with a JavaScript library.- ariaLabel
stringThe text screen readers read as the trigger's description, instead of the tooltip's text as it was when it opened. Bind it when the text changes while open.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- side
"top" | "right" | "bottom" | "left"The side of the trigger to open on. Flips to the other side when there is no room, unlessavoidCollisionsis off.- sideOffset
4 numberDistance in pixels from the trigger.- align
"start" | "center" | "end"Alignment against the trigger along the chosen side.- alignOffset
numberOffset in pixels from thealignposition.- avoidCollisions
booleanKeeps the tooltip inside the collision boundary by flipping and shifting it.- collisionBoundary
Element | (Element | null)[] | nullThe element or elements used as the collision boundary. The viewport by default.- collisionPadding
8 number | Partial<Record<"top" | "right" | "bottom" | "left", number>>Distance in pixels from the boundary edges where collisions start.- arrowPadding
numberPadding between an arrow and the tooltip's corners.- sticky
"partial" | "always"partialkeeps the tooltip attached to the trigger while scrolling;alwaysalso lets it detach from the trigger to stay in the boundary.- hideWhenDetached
booleanHides the tooltip when the trigger is scrolled out of view.- positionStrategy
"absolute" | "fixed"The CSS position used to place the tooltip.- updatePositionStrategy
"always" | "optimized"alwaysrecomputes the position on every animation frame instead of only on layout changes.
Emits
- escapeKeyDown
[event: KeyboardEvent]Fires on Escape. CallpreventDefault()to keep it open.- pointerDownOutside
[event: Event]Fires on a pointer press outside. CallpreventDefault()to keep it open.
Slots
- default
{}The tooltip's text, and an optionalTooltipArrow.
Props
- width
numberWidth of the arrow in pixels.- height
numberHeight of the arrow in pixels.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render. An SVG by default.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| tooltip-trigger | data-state | The trigger, a button by default. data-state is closed, delayed-open or instant-open. |
| tooltip-content | data-state, data-side, data-align, data-touch, data-instant | The tooltip. data-touch when a long press opened it; data-instant when it closes without its exit animation. |
| tooltip-arrow | — | The arrow. |
Accessibility
| Key | Action |
|---|---|
| Tab | Moves focus to the trigger, which opens the tooltip. |
| Escape | Closes the tooltip. |
While the tooltip is open, screen readers read its text after the trigger's name. With role="label", they read only the trigger's name.