# Tooltip

> A short ink label that describes its trigger on hover and keyboard focus. Comes in sizes xs to xl and takes Popup props directly.

Source: https://vaneui.com/docs/overlay-components/tooltip

Import: `import { Tooltip, Button, IconButton, PopupTrigger, Row, Text, ThemeProvider } from "@vaneui/ui"`

Tooltip is for hints of a few words, such as a keyboard shortcut or the full text of an abbreviation. The hint renders as a Popup with `role="tooltip"`, so opening it does not move focus. For content the user clicks into, such as a form or a list of links, open a [Popup](/docs/overlay-components/popup) on click instead; for a list of actions, use a [Menu](/docs/overlay-components/menu).

## Basic usage

Tooltip describes its trigger with a short hint on hover and on keyboard focus. Pass the trigger as the child and the hint as `content`. The hint renders as an ink label: near-black in light mode, near-white in dark mode.

```tsx demo
<Tooltip content="Saves without leaving the page">
  <Button>Save</Button>
</Tooltip>
```

The trigger must accept a ref. `Button`, `IconButton`, `Badge`, `Link` and the other element components do.

Tooltip takes [Popup](/docs/overlay-components/popup) props directly (size, appearance, variant, shape, placement, `arrow`, `offset`, `className` and the rest), and they style the label. Its own props are `content`, `open`, `defaultOpen`, `onOpenChange`, `openDelay` (default `300`), `closeDelay` (default `100`), `popupProps`, `popupId` and `disabled`.

## Keyboard and pointer

A tooltip that only opens on hover is invisible to keyboard users, so Tooltip opens on focus too. Tab to the second button to see it.

```tsx demo
<Row flexWrap>
  <Tooltip content="Opens on hover">
    <Button secondary>Hover me</Button>
  </Tooltip>
  <Tooltip content="Opens on focus as well">
    <Button secondary>Tab to me</Button>
  </Tooltip>
</Row>
```

## Sizes

Tooltip defaults to `sm`. Its text, padding and corner radius follow its own size, `xs` to `xl`, and the text sits one font step under a Button of the same size. The tooltip does not shrink on phones.

```tsx demo
<Row flexWrap>
  <Tooltip xs content="An xs tooltip">
    <Button xs>xs</Button>
  </Tooltip>
  <Tooltip content="An sm tooltip, the default">
    <Button>sm</Button>
  </Tooltip>
  <Tooltip md content="An md tooltip">
    <Button md>md</Button>
  </Tooltip>
  <Tooltip lg content="An lg tooltip">
    <Button lg>lg</Button>
  </Tooltip>
  <Tooltip xl content="An xl tooltip">
    <Button xl>xl</Button>
  </Tooltip>
</Row>
```

## Placement

Tooltip opens above its trigger and flips to the other side when there is no room. All twelve `place*` props from Popup work on `Tooltip` directly, and `arrow` adds a pointer. With `arrow`, the gap (`offset`, 4px by default) is measured from the arrow tip, so the tip sits that far from the trigger instead of touching it. Top and bottom tooltips stay on screen when the trigger sits at the edge of the viewport.

```tsx demo
<Row flexWrap>
  <Tooltip content="Above">
    <Button>Top</Button>
  </Tooltip>
  <Tooltip placeBottom content="Below">
    <Button>Bottom</Button>
  </Tooltip>
  <Tooltip placeRight content="To the right">
    <Button>Right</Button>
  </Tooltip>
  <Tooltip placeRight arrow content="Points at its trigger">
    <Button>Arrow</Button>
  </Tooltip>
</Row>
```

## Long hints

A long hint wraps inside a width cap that grows with size, from 16 to 32rem across `xs` to `xl` and 20rem at the default `sm`, instead of running across the page.

```tsx demo
<Tooltip content="Archiving moves the conversation out of your inbox. Replies bring it back, and nothing is deleted.">
  <Button secondary>Archive</Button>
</Tooltip>
```

## Color and shape

Appearance, variant and shape props restyle the label. `secondary` restores the gray look of earlier versions.

```tsx demo
<Row flexWrap>
  <Tooltip content="Ink, the default">
    <Button>default</Button>
  </Tooltip>
  <Tooltip secondary content="Gray">
    <Button>secondary</Button>
  </Tooltip>
  <Tooltip danger content="Deletes the project for everyone">
    <Button danger>danger</Button>
  </Tooltip>
  <Tooltip sharp content="Sharp corners">
    <Button>sharp</Button>
  </Tooltip>
  <Tooltip outline danger border content="Outline danger">
    <Button>outline danger</Button>
  </Tooltip>
</Row>
```

To change every tooltip in an app, set the default once on [`ThemeProvider`](/docs/customization/using-theme-provider):

```tsx
<ThemeProvider themeDefaults={{ tooltip: { secondary: true } }}>
  <App />
</ThemeProvider>
```

`popupProps` is still supported and is combined with the direct props, which helps when several tooltips share one props object. Pass one value per category (one size, one appearance, and so on) across the two.

## Delays

`openDelay` keeps tooltips from flashing as the pointer crosses the screen. `closeDelay` gives the pointer time to move onto the tooltip itself.

```tsx demo
<Row flexWrap>
  <Tooltip content="Appears at once" openDelay={0}>
    <Button>No delay</Button>
  </Tooltip>
  <Tooltip content="Waits half a second" openDelay={500}>
    <Button>Slow</Button>
  </Tooltip>
</Row>
```

## Accessibility

A tooltip describes its trigger, so while it is open the trigger carries `aria-describedby` pointing at it. It never gets `aria-haspopup` or `aria-expanded`, because those describe a disclosure, not a description, and there is no `aria-haspopup` value for tooltips.

Keep the content short and non-essential. Anything the user must read to complete a task belongs in the page, not behind a hover.

## Icon-only triggers

A common use is explaining a control that has no visible label.

```tsx demo
<Row>
  <Text sm>API key</Text>
  <Tooltip content="Rotating the key invalidates the old one immediately">
    <IconButton secondary aria-label="About API keys">?</IconButton>
  </Tooltip>
</Row>
```

## Tooltip on a Menu or PopupTrigger trigger

A Tooltip can be the trigger of a [Menu](/docs/overlay-components/menu) or a `PopupTrigger`. The ref, event handlers and `aria-*` attributes they pass to their trigger go on to the Tooltip's child, so a click opens the popup, it anchors to the button, and the tooltip still describes it on hover and focus. This needs `@vaneui/ui` 1.5.0 or later.

```tsx demo
<PopupTrigger popup={<Text sm>Display settings</Text>}>
  <Tooltip content="Settings">
    <IconButton aria-label="Settings"><Settings /></IconButton>
  </Tooltip>
</PopupTrigger>
```

## Props

| Prop | Category | Default | Description |
| --- | --- | --- | --- |
| `primary` | Appearance | yes | Primary color appearance (gray) |
| `accent` | Appearance |  | Accent color appearance (rose) |
| `secondary` | Appearance |  | Secondary color appearance (gray) |
| `tertiary` | Appearance |  | Tertiary color appearance |
| `success` | Appearance |  | Success color appearance (green) |
| `danger` | Appearance |  | Danger color appearance (red) |
| `warning` | Appearance |  | Warning color appearance (amber) |
| `info` | Appearance |  | Info color appearance (cyan) |
| `inheritAppearance` | Appearance |  | Inherit appearance from parent — suppresses own data-appearance/data-variant, uses parent's CSS variables |
| `flex1` | Flex |  | Take up remaining space (= `flex-1`, i.e. `flex: 1 1 0%`) |
| `flexAuto` | Flex |  | Grow but respect intrinsic size (= `flex-auto`, i.e. `flex: 1 1 auto`) |
| `flexNone` | Flex |  | Don't grow and don't shrink (= `flex-none`, i.e. `flex: none`) |
| `fontSans` | Font Family | yes | Sans-serif font family (default) — emits font-sans |
| `fontSerif` | Font Family |  | Serif font family — emits font-serif |
| `fontMono` | Font Family |  | Monospace font family — emits font-mono |
| `fontHeading` | Font Family |  | Heading font family (defaults to sans, customizable via --font-heading) — emits font-heading |
| `italic` | Font Style |  | Italic font style |
| `notItalic` | Font Style |  | Not italic (normal) font style |
| `fontThin` | Font Weight |  | Thin font weight (100) — emits font-thin |
| `fontExtralight` | Font Weight |  | Extra light font weight (200) — emits font-extralight |
| `fontLight` | Font Weight |  | Light font weight (300) — emits font-light |
| `fontNormal` | Font Weight |  | Normal font weight (400) — emits font-normal |
| `fontMedium` | Font Weight |  | Medium font weight (500) — emits font-medium |
| `fontSemibold` | Font Weight |  | Semibold font weight (600) — emits font-semibold |
| `fontBold` | Font Weight |  | Bold font weight (700) — emits font-bold |
| `fontExtrabold` | Font Weight |  | Extra bold font weight (800) — emits font-extrabold |
| `fontBlack` | Font Weight |  | Black font weight (900) — emits font-black |
| `padding` | Padding |  | Enable internal padding |
| `paddingX` | Padding |  | Enable only horizontal padding |
| `paddingY` | Padding |  | Enable only vertical padding |
| `noPadding` | Padding |  | Disable internal padding |
| `placeTop` | Placement | yes | Position above anchor, centered horizontally (default) |
| `placeTopStart` | Placement |  | Position above anchor, aligned to start (left) |
| `placeTopEnd` | Placement |  | Position above anchor, aligned to end (right) |
| `placeBottom` | Placement |  | Position below anchor, centered horizontally |
| `placeBottomStart` | Placement |  | Position below anchor, aligned to start (left) |
| `placeBottomEnd` | Placement |  | Position below anchor, aligned to end (right) |
| `placeLeft` | Placement |  | Position to the left of anchor, centered vertically |
| `placeLeftStart` | Placement |  | Position to the left of anchor, aligned to top |
| `placeLeftEnd` | Placement |  | Position to the left of anchor, aligned to bottom |
| `placeRight` | Placement |  | Position to the right of anchor, centered vertically |
| `placeRightStart` | Placement |  | Position to the right of anchor, aligned to top |
| `placeRightEnd` | Placement |  | Position to the right of anchor, aligned to bottom |
| `pill` | Shape |  | Fully rounded corners (circular) |
| `sharp` | Shape |  | No rounded corners (square) |
| `rounded` | Shape | yes | Medium rounded corners (default) |
| `noShrink` | Shrink |  | Prevent the flex item from shrinking below its content size (= `shrink-0`) |
| `xs` | Size |  | Extra small size |
| `sm` | Size | yes | Small size |
| `md` | Size |  | Medium size (default) |
| `lg` | Size |  | Large size |
| `xl` | Size |  | Extra large size |
| `textLeft` | Text Align |  | Align text to left (physical side, does not flip under RTL) |
| `textCenter` | Text Align |  | Align text to center |
| `textRight` | Text Align |  | Align text to right (physical side, does not flip under RTL) |
| `textJustify` | Text Align |  | Justify text |
| `textStart` | Text Align |  | Align text to the reading-direction start (left in LTR, right in RTL) |
| `textEnd` | Text Align |  | Align text to the reading-direction end (right in LTR, left in RTL) |
| `underline` | Text Decoration |  | Add underline decoration below text |
| `lineThrough` | Text Decoration |  | Add strikethrough/line-through decoration across text |
| `noUnderline` | Text Decoration |  | Remove ALL text-decoration — underline, line-through, and overline (text-decoration: none) |
| `overline` | Text Decoration |  | Add overline decoration above text |
| `uppercase` | Text Transform |  | Transform text to uppercase |
| `lowercase` | Text Transform |  | Transform text to lowercase |
| `capitalize` | Text Transform |  | Capitalize first letter of each word |
| `normalCase` | Text Transform |  | Normal text case (no transformation) |
| `truncate` | Truncate |  | Single line truncation with ellipsis |
| `lineClamp2` | Truncate |  | Truncate at 2 lines with ellipsis |
| `lineClamp3` | Truncate |  | Truncate at 3 lines with ellipsis |
| `lineClamp4` | Truncate |  | Truncate at 4 lines with ellipsis |
| `lineClamp5` | Truncate |  | Truncate at 5 lines with ellipsis |
| `noTruncate` | Truncate |  | Remove truncation |
| `filled` | Variant | yes | Filled variant - solid background with contrasting text color |
| `outline` | Variant |  | Outline variant - transparent background with border and colored text (default) |
| `ghost` | Variant |  | Ghost variant - transparent background, no border, appearance-colored text, tinted hover background |

Layout and utility props (Align Self, Border, Clamp Height, Constrain Width, Display, Flex Direction, Gap, Height, Hide, Items, Justify, Justify Self, Overflow, Pointer Events, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).
