---
title: Tooltip
description: A short hint shown on hover or focus.
category: Feedback
status: beta
since: 0.3.4
tags: [tooltip, hint, overlay]
syncStatus: reviewed
verified: true
---

## Usage

:::TuffCodeBlock{lang="vue"}
---
code: |
  <template>
    <TxTooltip content="Copied">
      <TxButton variant="ghost">Copy</TxButton>
    </TxTooltip>
  </template>
---
:::

### Hover Hint
`trigger` defaults to `hover`; keyboard focus on the reference opens it too.
::TuffDemoWrapper{demo="TooltipHoverDemo" code-lang="vue"}
---
code: |
  <template>
    <TxTooltip content="Hint">
      <TxButton variant="ghost">Hover me</TxButton>
    </TxTooltip>
    <TxTooltip content="Info">
      <TxButton variant="ghost">Info</TxButton>
    </TxTooltip>
  </template>
---
::

### Icon Button
::TuffDemoWrapper{demo="TooltipButtonDemo" code-lang="vue"}
---
code: |
  <template>
    <TxTooltip content="Share">
      <TxButton icon="i-carbon-share" circle />
    </TxTooltip>
  </template>
---
::

### Anchor Config
`anchor` passes through to BaseAnchor and overrides defaults such as background, placement, and the arrow.
::TuffDemoWrapper{demo="TooltipIndicatorDemo" code-lang="vue"}
---
code: |
  <template>
    <TxTooltip
      content="Mask background + arrow"
      :anchor="{ showArrow: true, panelBackground: 'mask' }"
    >
      <TxButton variant="ghost">Status detail</TxButton>
    </TxTooltip>

    <TxTooltip
      content="Glass background + right placement"
      :anchor="{ placement: 'right', panelBackground: 'glass', panelShadow: 'medium' }"
    >
      <TxButton variant="ghost">Service status</TxButton>
    </TxTooltip>
  </template>
---
::

### Click Toggle
With `trigger="click"`, a reference click toggles it and an outside click closes it.
::TuffDemoWrapper{demo="TooltipClickOutsideCloseDemo" code-lang="vue"}
---
code: |
  <template>
    <TxTooltip v-model="open" trigger="click" content="Click to toggle, click outside to close">
      <TxButton variant="ghost">Click me</TxButton>
    </TxTooltip>
  </template>
---
::

### Keep Open on Outside Click
With `closeOnClickOutside` set to `false`, only another reference click or Escape closes it.
::TuffDemoWrapper{demo="TooltipClickOutsideKeepDemo" code-lang="vue"}
---
code: |
  <template>
    <TxTooltip
      v-model="open"
      trigger="click"
      :close-on-click-outside="false"
      content="Click to toggle, outside click will not close"
    >
      <TxButton variant="ghost">Pinned tooltip</TxButton>
    </TxTooltip>
  </template>
---
::

### Dashboard Feedback Center
A tooltip explains one action or metric; show lasting results with `TxToastHost` and block a refreshing panel with `TxLoadingOverlay`.
::TuffDemoWrapper{demo="ComponentsFeedbackTaskCenterDemo" code-lang="vue"}
---
code: |
  <template>
    <TxTooltip
      content="Tooltip explains the current action only."
      :anchor="{ placement: 'bottom', panelBackground: 'glass' }"
    >
      <TxButton variant="secondary">Send toast</TxButton>
    </TxTooltip>
  </template>
---
::

### Best Practices

- Keep the text to one line.
- Configure looks, placement, and motion through `anchor`.
- Don't put forms, long explanations, or bulk actions in a tooltip; move complex content to `TxPopover` or `TxDrawer`.

## API Reference

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `modelValue` | `boolean` | `undefined` | Whether it is open (`v-model`); omit it for uncontrolled use. |
| `content` | `string` | `''` | Hint text; unused when the `content` slot is provided. |
| `disabled` | `boolean` | `false` | Blocks opening and closes the tooltip when it becomes disabled. |
| `trigger` | `'hover' \| 'click' \| 'focus' \| 'manual'` | `'hover'` | How it opens; `manual` binds no reference interaction, so `modelValue` alone decides. |
| `openDelay` | `number` | From the `layer` preset (`200` for `hint`) | Open delay in ms for hover or focus; the shared delay service supplies it when unset. |
| `closeDelay` | `number` | From the `layer` preset (`120` for `hint`) | Close delay in ms for hover or focus; the shared delay service supplies it when unset. |
| `maxHeight` | `number` | `320` | Panel max height in px; `<= 0` removes it, as does using the `content` slot with it unset. |
| `referenceFullWidth` | `boolean` | `false` | Stretches the reference wrapper to full width. |
| `interactive` | `boolean` | `false` | In hover mode, lets the pointer move into the panel without closing it. |
| `keepAliveContent` | `boolean` | `false` | Keeps panel content mounted after close. |
| `closeOnClickOutside` | `boolean` | `trigger === 'click'` | Closes on an outside click; takes precedence over the same key in `anchor`. |
| `toggleOnReferenceClick` | `boolean` | `trigger === 'click'` | Toggles on reference click; takes precedence over the same key in `anchor`. |
| `layer` | `'hint' \| 'menu' \| 'dialog'` | `'hint'` | Semantic overlay layer; picks the delay preset, exclusion rules, and default animation. |
| `role` | `string` | `'tooltip'` | Panel ARIA role; any value but `tooltip` also drops the reference's `aria-describedby`. |
| `unstyled` | `boolean` | `false` | Renders the content bare, without tooltip typography or the height cap. |
| `anchor` | `Partial<TooltipAnchorProps>` | `{}` | Passed to `TxBaseAnchor`, overriding the tooltip's placement, panel, and animation defaults; excludes `modelValue` and `disabled`. |

### Events

| Event | Payload | Description |
|------|---------|-------------|
| `update:modelValue` | `(value: boolean) => void` | Fires when the open state changes. |
| `open` | `() => void` | Fires after the tooltip opens. |
| `close` | `() => void` | Fires after the tooltip closes. |

### Slots

| Slot | Props | Description |
|------|------|-------------|
| `default` | - | Reference content, wrapped in the trigger span. |
| `content` | `{ side: string }` | Custom tooltip body; `side` is the final side. |

### Exposed Methods

| Name | Type | Description |
|------|------|-------------|
| `updatePosition` | `() => void` | Recomputes the panel position. |

## Overview

- With `modelValue` it is controlled; otherwise it keeps its own open state.
- Hover and focus open and close on `openDelay` / `closeDelay`; with `click`, BaseAnchor handles toggling and outside clicks.
- With `interactive`, the hover zone is the whole floating layer: the panel box, padding included, plus the hover bridge to the reference. The close is scheduled only on leaving all of it.
- Also only with `interactive`: once the pointer leaves the reference toward the panel, it stays open while the pointer keeps moving inside the safe triangle. Parents stay open and hover triggers on the way do not open. A 100ms stop or a step outside closes it on `closeDelay`, and a trigger stopped on takes over.
- The panel body carries `role="tooltip"` and `data-side`.
- The default animation is `{ type: 'boom' }`, which `anchor.animation` replaces entirely. No arrow is drawn by default; with one, the gap is still `offset` (8px by default).

## Technologies

- The safe triangle lives in `packages/tuffex/packages/utils/hover-intent.ts`, which listens to `pointermove` only during a trip; the anchor-delay service holds parent panels' deferred closes.
- Source: `packages/tuffex/packages/components/src/tooltip/`.

<TuffDocSourceLink />