> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.servicetitan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tooltip - Web

> Tooltips are floating labels that add quick clarity to an element.

> [!NOTE]
>
> For development, import `Tooltip` from
> `@servicetitan/anvil2`. For design, find it in the
> [Anvil2 file](https://www.figma.com/design/xaNQsvRKczoxu7pj0M6QT8/Anvil2-v3?node-id=159-439).

![](https://mintcdn.com/servicetitan/uz2PQSvO75TRhQ38/images/docs/web/components/shared/overview-of-a-tooltip.png?fit=max\&auto=format\&n=uz2PQSvO75TRhQ38\&q=85\&s=1d030723c589e28470ff04c45cb3893b)

## Anatomy

The Tooltip consists of three primary elements that work together to add quick clarity to an element.

![Anatomy of a
Tooltip](https://mintcdn.com/servicetitan/ar8TJanaRSxOpbCO/images/docs/web/components/tooltip/design/anatomy-of-a-tooltip.png?fit=max\&auto=format\&n=ar8TJanaRSxOpbCO\&q=85\&s=8bca80c134d7b4733603eed7b252c942)

1. Tooltip background, content
2. Caret
3. Trigger

## Options

The Tooltip supports the following configurations to accommodate various supplementary information scenarios.

### Content

#### Text content

![Tooltip options
text](https://mintcdn.com/servicetitan/q4u7k_VQHH_NqAgi/images/docs/web/components/tooltip/design/tooltip-options-text.png?fit=max\&auto=format\&n=q4u7k_VQHH_NqAgi\&q=85\&s=507f6ed133049251e82e7ab4152495c0)

By default, Tooltips support a basic string of text, with only minimal additions that can be added, such as emojis.

#### Custom content

![Text options custom
content](https://mintcdn.com/servicetitan/ar8TJanaRSxOpbCO/images/docs/web/components/tooltip/design/text-options-custom-content.png?fit=max\&auto=format\&n=ar8TJanaRSxOpbCO\&q=85\&s=1b09d04729805f788e87ce40b65453d7)

Content within the Tooltip can be customized beyond text, but only with non-interactive elements.

### Placement

![Tooltip options
placement](https://mintcdn.com/servicetitan/q4u7k_VQHH_NqAgi/images/docs/web/components/tooltip/design/tooltip-options-placement.png?fit=max\&auto=format\&n=q4u7k_VQHH_NqAgi\&q=85\&s=7098559e5cff3f0b4acc560bc3cc412b)

Tooltip placement adjusts automatically when insufficient space is available. See behaviors for details.

### Visual States

Tooltips open when the trigger element is in a hover or focus state. Avoid removing opening on focus, as this prevents keyboard-only users from viewing Tooltips.

![Tooltip visual
states](https://mintcdn.com/servicetitan/q4u7k_VQHH_NqAgi/images/docs/web/components/tooltip/design/tooltip-visual-states.png?fit=max\&auto=format\&n=q4u7k_VQHH_NqAgi\&q=85\&s=b34e60db2d40031236faf755d95f7b8e)

A Tooltip appearing on both the hover and focus state of a Button.

## Behavior

The Tooltip responds to space constraints with automatic positioning adjustments and overflow handling.

### Overflow handling

![Tooltip behavior overflow
handling](https://mintcdn.com/servicetitan/ar8TJanaRSxOpbCO/images/docs/web/components/tooltip/design/tooltip-behavior-overflow-handling.png?fit=max\&auto=format\&n=ar8TJanaRSxOpbCO\&q=85\&s=c6bbf6620dd34337b7de42019e269418)

Text in a Tooltip will wrap. The max-width of a Tooltip is 272px or 17rem, while the text region is 256px or 16rem.

## Usage Guidelines

| Standard | Requirement |
| - | - |
| DoSupplementary information for interactive elements | Use the Tooltip as supplementary information for interactive elements on the page. |
| DoDescribe Button Icons | The meaning behind icons is usually not universally understood. Adding a Tooltip can support the understanding of a Button Icon. |
| DoUse under space constraints | When space is constrained, use Tooltips for supplemental information such as definitions and contextual help. Consider inline text as an alternative in most cases. |
| DoUse for informational overlays | Tooltip is the component of choice for tips and other informational overlays. Use a [Popover](https://anvil.servicetitan.com/docs/components/popover/web.md) in place of a Tooltip when actions are needed. |
| DoPosition to avoid screen edges and obstruction | When elements are placed toward a screen edge, position Tooltips to open in the opposite direction, and position them to minimize obstruction of important elements. When neither consideration applies, use the top position as the default placement. |
| DoApply only to keyboard-accessible elements | For a Tooltip to be accessible by keyboard and screen readers, the element it is tied to must be keyboard accessible, typically some form of button or link. |
| Don'tUse for error messaging | Avoid using Tooltips for error messaging. Use inline error messages or Field Message components instead. |
| Don'tUse for critical information | Information essential to the completion of the task should be visible on the page, not only in a Tooltip. |
| Don'tApply to disabled elements | Avoid adding Tooltips to disabled elements. Disabled elements are not keyboard accessible. Add the Tooltip information on the page itself, or provide a dedicated help Button Icon. |
| Don'tAdd interactive elements | Tooltips should not have interactive elements. If an overlay needs interactive elements, use the [Popover](https://anvil.servicetitan.com/docs/components/popover/web.md) instead; see [Tooltip vs Popover](#tooltip-vs-popover). For other interactive elements, add this information on the page itself, or provide a dedicated help Button Icon. |

### Alternatives

Tooltips are generally difficult to both discover and use on the page, particularly for touch device users. Explore alternatives to a Tooltip first, such as inline text.

#### Tooltip vs Popover

Tooltip is the component of choice for tips and other informational overlays. Popovers may be used in place of a Tooltip when actions are needed.

| Usage | Tooltip | Popover |
| - | - | - |
| Can have a link? | Should not have interactive elements | Yes |
| Can have other interactive elements? | Should not have interactive elements | Yes |
| Open mechanic? | Hover or Focus | Click/Press, option for Hover or Focus |
| Can trap user focus? | No | Yes |

## Content

Content within the Tooltip should be brief, clear, and supplementary to the trigger element.

### Keep content 1-2 lines

When content extends to 3+ lines, it is strongly encouraged to find another method of conveying the information.

![Tooltip content short
do](https://mintcdn.com/servicetitan/ar8TJanaRSxOpbCO/images/docs/web/components/tooltip/design/tooltip-content-short-do.png?fit=max\&auto=format\&n=ar8TJanaRSxOpbCO\&q=85\&s=3777709b8c94315d18427d7910d4e2e7)

> [!TIP]
>
> **Do**

![Tooltip content short
don't](https://mintcdn.com/servicetitan/ar8TJanaRSxOpbCO/images/docs/web/components/tooltip/design/tooltip-content-short-dont.png?fit=max\&auto=format\&n=ar8TJanaRSxOpbCO\&q=85\&s=3d3094fd02ceea6bd980265e8f327ec5)

> [!CAUTION]
>
> **Don't**

### Don't repeat the content of the Tooltip's trigger

Avoid repeating the trigger's content in the Tooltip, even in UIs that heavily use Tooltips. Omitting a redundant Tooltip is preferred over consistent Tooltip usage in the UI.

![Tooltip content repeat
don't](https://mintcdn.com/servicetitan/ar8TJanaRSxOpbCO/images/docs/web/components/tooltip/design/tooltip-content-repeat-dont.png?fit=max\&auto=format\&n=ar8TJanaRSxOpbCO\&q=85\&s=b8950ed7c69e41b1f68e8097ee4f4585)

> [!CAUTION]
>
> **Don't**

## Keyboard Interaction

Users can navigate the Tooltip using standard keyboard controls.

| Key | Description |
| - | - |
| Tab | When focusing on the trigger, activates the Tooltip |
| Escape | Hides the Tooltip |

### Accessibility

Anvil provides accessibility needs out of the box. Annotating labels is the main piece needed in a design.

#### Provide Tooltip labels for Icon Buttons

Provide a label to describe the action for both screen readers and users who focus on the element, regardless of whether a label is visible on the page.

For more guidance on labels and context, see [input field context association best practices](https://anvil.servicetitan.com/docs/accessibility/labels-and-ctas.md#input-field-context-association).

## Code

**Implementation**

tooltip-playground

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/tooltip-playground?file=src/App.tsx)

```tsx lines expandable theme={null}
import { Tooltip, Button } from "@servicetitan/anvil2";
import Info from "@servicetitan/anvil2/assets/icons/material/round/edit.svg";

function App() {
  return (
    <Tooltip defaultOpen>
      <Tooltip.Trigger>
        <Button icon={Info}>Hover over me</Button>
      </Tooltip.Trigger>
      <Tooltip.Content>This is a tooltip!</Tooltip.Content>
    </Tooltip>
  );
}

export default App;
```

## Common Examples

The `Tooltip` component is used to add a floating label to an element, usually triggered on hover or focus.

```tsx theme={null}
import { Tooltip } from "@servicetitan/anvil2";

function ExampleComponent() {
  return (
    <Tooltip>
      <Tooltip.Trigger>
        <span>Hover to open</span>
      </Tooltip.Trigger>
      <Tooltip.Content>Tooltip Content</Tooltip.Content>
    </Tooltip>
  );
}
```

### Controlling tooltip state

By default, the open state of a tooltip is managed internally and opens when the trigger element has hover or focus.

To manually control the open state of the tooltip, use the `open` prop.

tooltip-controlled

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/tooltip-controlled?file=src/App.tsx)

```tsx lines expandable theme={null}
import { Tooltip, Flex, Button } from "@servicetitan/anvil2";
import { useState } from "react";

function App() {
  const [open, setOpen] = useState(true);

  return (
    <Flex justifyContent="center">
      <Tooltip open={open}>
        <Tooltip.Trigger>
          <Button
            onClick={() => {
              setOpen((prev) => !prev);
            }}
          >
            Click to toggle
          </Button>
        </Tooltip.Trigger>
        <Tooltip.Content>This is a tooltip!</Tooltip.Content>
      </Tooltip>
    </Flex>
  );
}

export default App;
```

### Adjusting tooltip offset

In some cases, the context around the tooltip trigger may require the tooltip to render further away from or closer to the trigger.

In these cases, adjust the `offset` prop, which accepts a number representing pixels.

tooltip-offset

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/tooltip-offset?file=src/App.tsx)

```tsx lines expandable theme={null}
import { Tooltip, Card, Button, Text } from "@servicetitan/anvil2";

function App() {
  return (
    <Card
      gap={4}
      alignItems="center"
      style={{
        background: "var(--background-color-inverted-strong)",
      }}
    >
      <Tooltip offset={24} defaultOpen>
        <Tooltip.Trigger>
          <Button appearance="primary">Hover over me</Button>
        </Tooltip.Trigger>
        <Tooltip.Content style={{ maxWidth: "20rem" }}>
          Prevent the tooltip background from getting lost in the card
          background.
        </Tooltip.Content>
      </Tooltip>
      <Text
        style={{
          color: "var(--foreground-color-inverted)",
        }}
      >
        Lorem ipsum dolor sit amet.
      </Text>
    </Card>
  );
}

export default App;
```

**Tooltip Props**

```tsx theme={null}
<Tooltip
  defaultOpen={false}
  disableFlip={false}
  disableShift={false}
  fallbackPlacements={["bottom", "bottom-start"]}
  offset={5}
  open={false}
  placement="top"
  onOpenChange={(open) => console.log(open)}
>
  <Tooltip.Trigger>
    <span>Hover to open</span>
  </Tooltip.Trigger>
  <Tooltip.Content>Tooltip Content</Tooltip.Content>
</Tooltip>
```

## `Tooltip` Props

The `Tooltip` component is expected to contain both the `Tooltip.Trigger`, which will show the tooltip when hovered and serve as a reference for where the tooltip will be placed, and the `Tooltip.Content`, which defines what content will be shown inside the tooltip itself.

**defaultOpen** `boolean` (default: false)

**delay** `number` (default: 100)

Delay in milliseconds before showing the tooltip.

**disableFlip** `boolean` (default: false)

**disableShift** `boolean` (default: false)

**fallbackPlacements** `Placement[]`

e.g. `["bottom", "bottom-start"]`

**offset** `number` (default: 5)

The distance (in `px`) between the tooltip and trigger.

**onOpenChange** `(open: boolean) =\> void`

**open** `boolean`

Controls the open state of the tooltip (controlled mode).

**openOnHover** `boolean`

Changes interaction to use hover instead of focus.

**placement** `"top" | "right" | "bottom" | "left" | "top-start" | "top-end" | "right-start" | "right-end" | "bottom-start" | "bottom-end" | "left-start" | "left-end"` (default: top)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.