# Tooltip

Shows a short label for a control on hover or focus.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Tooltip.tsx)

Figma: [Tooltip](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=3084-1076) (`Tooltip.Popup`)

## Overview

A tooltip is a visual label that opens on hover and keyboard focus.

## Examples

### Basic

```tsx
import { Button, Tooltip } from '@tempoxyz/ds'
import { Plus } from '@tempoxyz/ds/icons'

export function Demo() {
  return (
    <Tooltip.Provider>
      <Tooltip.Root>
        <Tooltip.Trigger
          render={<Button aria-label="Add funds" shape="icon" variant="secondary" />}
        >
          <Plus />
        </Tooltip.Trigger>
        <Tooltip.Popup>Add funds</Tooltip.Popup>
      </Tooltip.Root>
    </Tooltip.Provider>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Tooltip/Basic.tsx)

### Side

Set `side` on `Tooltip.Popup` to `top` (default), `bottom`, `left`, or `right`.

```tsx
import { Button, Tooltip } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Tooltip.Provider>
      <Tooltip.Root>
        <Tooltip.Trigger render={<Button variant="secondary" />}>Bottom</Tooltip.Trigger>
        <Tooltip.Popup side="bottom">Shown below the trigger</Tooltip.Popup>
      </Tooltip.Root>
    </Tooltip.Provider>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Tooltip/Side.tsx)

### Disabled

Wrap a disabled control in a focusable trigger. Disabled elements receive no pointer or focus events.

```tsx
import { Button, Tooltip } from '@tempoxyz/ds'
import { Refresh } from '@tempoxyz/ds/icons'

export function Demo() {
  return (
    <Tooltip.Provider>
      <Tooltip.Root>
        <Tooltip.Trigger render={<span tabIndex={0} />}>
          <Button aria-label="Refresh balances" disabled shape="icon" variant="secondary">
            <Refresh />
          </Button>
        </Tooltip.Trigger>
        <Tooltip.Popup>Refresh balances</Tooltip.Popup>
      </Tooltip.Root>
    </Tooltip.Provider>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Tooltip/Disabled.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Tooltip } from '@tempoxyz/ds'

<Tooltip.Provider>
  <Tooltip.Root>
    <Tooltip.Trigger />
    <Tooltip.Popup />
  </Tooltip.Root>
</Tooltip.Provider>
```

## Guidelines

### When to Use

* Label an icon-only button, such as Refresh balances, Filter activity, or Settings.
* Name a control whose icon is ambiguous, such as an arrow that could mean Send or Export.

### When Not to Use

* Use a [Popover](/docs/components/popover) with `openOnHover` on `Popover.Trigger` for info icons, such as the explanation beside a dashboard metric.
* Use visible text, such as a `Field.Description` from [Field](/docs/components/field), for fees, limits, requirements, and errors.
* Use an [Alert](/docs/components/alert) for warnings.
* Write the reason for a disabled [Button](/docs/components/button) in nearby text, not in a tooltip.
* Don't add a tooltip to a [Button](/docs/components/button) with a visible label. It repeats the label and covers nearby content.

### Use Tooltips as Labels Only

Focus stays on the trigger while the tooltip is open, so Tab can't reach a link or button inside it.

**Do:** Name the action of an icon-only button in a few words.

```tsx
/**
 * Do example for "Use Tooltips as Labels Only" on the Tooltip page.
 * Name the action of an icon-only button in a few words.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'
import { Filter } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <div {...styles.tooltip()}>Filter activity</div>
      <Button aria-label="Filter activity" shape="icon" variant="secondary">
        <Filter />
      </Button>
    </div>
  )
}

namespace styles {
  export const stack = style({
    alignItems: 'center',
    display: 'flex',
    flexDirection: 'column',
    rowGap: '8',
  })

  export const tooltip = style({
    backgroundColor: 'content.primary',
    borderRadius: 'xs',
    color: 'background.primary',
    paddingBlock: '6px !custom',
    paddingInline: '12',
    typography: 'body.b3',
  })
}
```

**Don't:** Put links, buttons, or other controls in a tooltip. Use a
[Popover](/docs/components/popover).

```tsx
/**
 * Don't example for "Use Tooltips as Labels Only" on the Tooltip page.
 * Don't put links, buttons, or other controls in a tooltip. Use a Popover.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'
import { InfoCircle } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <div {...styles.tooltip()}>
        Fees depend on network load. <span {...styles.link()}>Learn more</span>
      </div>
      <Button aria-label="About network fees" shape="icon" size="small" variant="tertiary">
        <InfoCircle />
      </Button>
    </div>
  )
}

namespace styles {
  export const link = style({ textDecorationLine: 'underline !custom' })

  export const stack = style({
    alignItems: 'center',
    display: 'flex',
    flexDirection: 'column',
    rowGap: '8',
  })

  export const tooltip = style({
    backgroundColor: 'content.primary',
    borderRadius: 'xs',
    color: 'background.primary',
    maxWidth: '14rem !custom',
    paddingBlock: '6px !custom',
    paddingInline: '12',
    typography: 'body.b3',
  })
}
```

### Keep Essential Information Visible

Touch input never opens a tooltip, and screen readers don't announce it. Show amounts, fees, and requirements as text on the page.

**Do:** Show the fee and its explanation as visible text.

```tsx
/**
 * Do example for "Keep Essential Information Visible" on the Tooltip page.
 * Show the fee and its explanation as visible text.
 * @module
 */
import { style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <div {...styles.text()}>
        <span {...styles.label()}>Network fee</span>
        <span {...styles.hint()}>Paid in the token you send</span>
      </div>
      <span {...styles.value()}>0.001 USDC</span>
    </div>
  )
}

namespace styles {
  export const hint = style({ color: 'content.secondary', typography: 'body.b3' })

  export const label = style({ color: 'content.primary', typography: 'body.b2Strong' })

  export const row = style({
    alignItems: 'center',
    columnGap: '24',
    display: 'flex',
    justifyContent: 'space-between',
    width: '16rem !custom',
  })

  export const text = style({ display: 'flex', flexDirection: 'column', rowGap: '4' })

  export const value = style({ color: 'content.primary', typography: 'body.b2' })
}
```

**Don't:** Hide a value you need to decide behind a tooltip.

```tsx
/**
 * Don't example for "Keep Essential Information Visible" on the Tooltip page.
 * Don't hide a value you need to decide behind a tooltip.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'
import { InfoCircle } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <div {...styles.tooltip()}>0.001 USDC, paid in the token you send</div>
      <div {...styles.row()}>
        <span {...styles.label()}>Network fee</span>
        <Button aria-label="Network fee" shape="icon" size="small" variant="tertiary">
          <InfoCircle />
        </Button>
      </div>
    </div>
  )
}

namespace styles {
  export const label = style({ color: 'content.primary', typography: 'body.b2Strong' })

  export const row = style({ alignItems: 'center', columnGap: '4', display: 'flex' })

  export const stack = style({
    alignItems: 'flex-end',
    display: 'flex',
    flexDirection: 'column',
    rowGap: '8',
  })

  export const tooltip = style({
    backgroundColor: 'content.primary',
    borderRadius: 'xs',
    color: 'background.primary',
    paddingBlock: '6px !custom',
    paddingInline: '12',
    typography: 'body.b3',
  })
}
```

### Group Tooltips With a Provider

* **Toolbars (Tooltip.Provider):** Wrap a row of icon buttons, so once one tooltip opens, its neighbors open instantly.
* **Single Triggers (600ms):** Keep the default `delay`. Shorter delays flash tooltips as the pointer passes.

### Place Tooltips Clear of Related Content

`Tooltip.Popup` flips when it would overflow the viewport. Set `side="bottom"` for triggers in a header or top toolbar.

**Do:** Choose a side that keeps the value the control acts on visible.

```tsx
/**
 * Do example for "Place Tooltips Clear of Related Content" on the Tooltip page.
 * Choose a side that keeps the value the control acts on visible.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'
import { Refresh } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.card()}>
      <span {...styles.label()}>Balance</span>
      <div {...styles.row()}>
        <span {...styles.value()}>1,250.00 USDC</span>
        <span {...styles.anchor()}>
          <Button aria-label="Refresh balance" shape="icon" size="small" variant="secondary">
            <Refresh />
          </Button>
          <span {...styles.tooltip()}>Refresh balance</span>
        </span>
      </div>
    </div>
  )
}

namespace styles {
  export const anchor = style({ display: 'flex', position: 'relative' })

  export const card = style({
    display: 'flex',
    flexDirection: 'column',
    height: '7rem !custom',
    rowGap: '4',
    width: '17rem !custom',
  })

  export const label = style({ color: 'content.secondary', typography: 'body.b3' })

  export const row = style({ alignItems: 'center', columnGap: '8', display: 'flex' })

  // Tooltips render in a portal, so this preview places one with the popup's styles, below the trigger.
  export const tooltip = style({
    backgroundColor: 'content.primary',
    borderRadius: 'xs',
    color: 'background.primary',
    paddingBlock: '6px !custom',
    paddingInline: '12',
    position: 'absolute',
    right: '0',
    top: 'calc(100% + 8px) !custom',
    typography: 'body.b3',
    whiteSpace: 'nowrap',
  })

  export const value = style({ color: 'content.primary', typography: 'heading.h2' })
}
```

**Don't:** Let the tooltip cover the value beside its trigger.

```tsx
/**
 * Don't example for "Place Tooltips Clear of Related Content" on the Tooltip page.
 * Don't let the tooltip cover the value beside its trigger.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'
import { Refresh } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.card()}>
      <span {...styles.label()}>Balance</span>
      <div {...styles.row()}>
        <span {...styles.value()}>1,250.00 USDC</span>
        <span {...styles.anchor()}>
          <Button aria-label="Refresh balance" shape="icon" size="small" variant="secondary">
            <Refresh />
          </Button>
          <span {...styles.tooltip()}>Refresh balance</span>
        </span>
      </div>
    </div>
  )
}

namespace styles {
  export const anchor = style({ display: 'flex', position: 'relative' })

  export const card = style({
    display: 'flex',
    flexDirection: 'column',
    height: '7rem !custom',
    rowGap: '4',
    width: '17rem !custom',
  })

  export const label = style({ color: 'content.secondary', typography: 'body.b3' })

  export const row = style({ alignItems: 'center', columnGap: '8', display: 'flex' })

  // Tooltips render in a portal, so this preview places one with the popup's styles, left of the trigger.
  export const tooltip = style({
    backgroundColor: 'content.primary',
    borderRadius: 'xs',
    color: 'background.primary',
    paddingBlock: '6px !custom',
    paddingInline: '12',
    position: 'absolute',
    right: 'calc(100% + 8px) !custom',
    top: '50% !custom',
    transform: 'translateY(-50%) !custom',
    typography: 'body.b3',
    whiteSpace: 'nowrap',
  })

  export const value = style({ color: 'content.primary', typography: 'heading.h2' })
}
```

## Content

### Write a Few Words

Use one to four words. Name the action, such as Refresh balances, not the icon, such as Circular arrows.

## Accessibility

A tooltip is visual only, so the trigger needs its own accessible name.

### Semantics

* **Tooltip.Trigger (button):** Keeps the role of the element it renders.
* **Tooltip.Popup:** Has no role and isn't linked to the trigger, so it neither names nor describes it. Mounts only while open.
* **Contrast (elevated):** Sets primary text on the elevated fill in both schemes.

### Keyboard

* **Open on Focus (Tab):** Focus on the trigger opens the tooltip at once.
* **Close the Tooltip (Escape):** Closes the tooltip while focus stays on the trigger.

### Focus

* **No Focus:** The tooltip never takes focus and holds no interactive content.
* **Pointer:** Opens after 600ms of hover. The pointer can move onto the popup without closing it.
* **Touch:** Touch input never opens it, so no task may depend on one.

### Your Responsibilities

* **Name Icon-Only Triggers (aria-label):** Name an icon-only trigger with the tooltip text.

## Related

[Popover](/docs/components/popover)

Use for info icons and interactive content.

[Button](/docs/components/button)

Use for icon-only buttons.

[CopyButton](/docs/components/copy-button)

Use for a copy action that names itself.

[Field](/docs/components/field)

Use for descriptions that stay visible.

[Dashboards](/docs/patterns/dashboards)

Covers metric explanations.
