Tooltip

new

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

Demo

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.

Toolbar

Keyboard shortcut

A Kbd inside a tooltip takes the tooltip's colours.

Shortcut

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.

Disabled

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.

Side

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.

Follow cursor

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>
Directive
FormMeaning
v-tooltip="'Save'"The text. An empty string, false, null or undefined shows nothing.
v-tooltip:bottomThe side: top, right, bottom or left.
v-tooltip.labelFor 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:

ValueBehaviour
autoThe 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-pressA long press everywhere.
offTouch 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)">
ReasonWhen
trigger-hoverThe pointer rested on the trigger, or left it.
trigger-focusThe trigger got keyboard focus, or lost it.
trigger-pressA long press opened it, or a press on the trigger closed it.
touch-releasetouchHideDelay passed after the finger lifted.
outside-pressA press outside the trigger and the tooltip.
escape-keyEscape.
scrollSomething holding the trigger scrolled.
sibling-openAnother tooltip opened. This one closes without its exit animation (data-instant).
disabledThe 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.

Data attributes

data-slotAttributesDescription
tooltip-triggerdata-stateThe trigger, a button by default. data-state is closed, delayed-open or instant-open.
tooltip-contentdata-state, data-side, data-align, data-touch, data-instantThe tooltip. data-touch when a long press opened it; data-instant when it closes without its exit animation.
tooltip-arrow—The arrow.

Accessibility

KeyAction
TabMoves focus to the trigger, which opens the tooltip.
EscapeCloses 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.

Changelog

  1. registry 0.23.0

    bc6008b — Exits now use the decelerating curve, like entrances. Collapsible, Accordion, the overlay surfaces (Popover, Select, Menu, Tooltip), Drawer, Toast and InnerLoading used to close on --ease-emphasized-accelerate, which holds still for most of its duration and then snaps shut; closing on --ease-standard-decelerate starts at once and settles gently, so the same duration feels faster. The tokens themselves are unchanged.

  2. core 0.17.0

    bc6008b — Exits now use the decelerating curve, like entrances. Collapsible, Accordion, the overlay surfaces (Popover, Select, Menu, Tooltip), Drawer, Toast and InnerLoading used to close on --ease-emphasized-accelerate, which holds still for most of its duration and then snaps shut; closing on --ease-standard-decelerate starts at once and settles gently, so the same duration feels faster. The tokens themselves are unchanged.

  3. registry 0.22.0

    4712efa — A Kbd inside a Button wrapped in TooltipTrigger as-child (or any other as-child trigger) keeps the button's colours, and an InputGroupButton wrapped the same way in a block addon keeps the addon's inset. The trigger's data-slot replaces the child's own, as in shadcn, so Kbd now keys on the <button> element (any button tints it, Toggle and Toolbar items included) and the block addon sets the inset on its children.

  4. registry 0.21.0

    5ada64b — A pressed Toggle or ToggleGroup item keeps its on look inside TooltipTrigger as-child (or any wrapper that writes its own data-state). The on styles read aria-pressed, which Reka sets on every toggle, instead of data-state="on", which the tooltip overwrote with closed; core's active-colour rules match both, so a custom [data-state="on"][data-active-color] rule keeps working.

  5. core 0.15.1

    5ada64b — A pressed Toggle or ToggleGroup item keeps its on look inside TooltipTrigger as-child (or any wrapper that writes its own data-state). The on styles read aria-pressed, which Reka sets on every toggle, instead of data-state="on", which the tooltip overwrote with closed; core's active-colour rules match both, so a custom [data-state="on"][data-active-color] rule keeps working.

  6. registry 0.5.0

    59f9254 — Add Tooltip, from shadcn-vue, with its behaviour in @kappa-ui/core/tooltip: it opens once the pointer rests on the trigger (moving restarts the wait), on keyboard focus only, and on a long press on touch screens; tooltips under a TooltipProvider warm up together; update:open reports why it opened or closed; role="label" suits icon buttons; followCursor keeps it at the pointer. v-tooltip gives the same tooltip from a string or an options object, with the side as its argument and .label for icon buttons. Button with aria-disabled="true" now looks disabled while keeping focus and pointer events, and swallows its click. A Kbd inside a tooltip takes the tooltip's colours.

  7. core 0.4.0

    59f9254 — Add Tooltip, from shadcn-vue, with its behaviour in @kappa-ui/core/tooltip: it opens once the pointer rests on the trigger (moving restarts the wait), on keyboard focus only, and on a long press on touch screens; tooltips under a TooltipProvider warm up together; update:open reports why it opened or closed; role="label" suits icon buttons; followCursor keeps it at the pointer. v-tooltip gives the same tooltip from a string or an options object, with the side as its argument and .label for icon buttons. Button with aria-disabled="true" now looks disabled while keeping focus and pointer events, and swallows its click. A Kbd inside a tooltip takes the tooltip's colours.