Tooltip - Web

For development, import Tooltip from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

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

Tooltip background, content
Caret
Trigger

Options

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

Content

Text content

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

Custom content

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

Placement

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.

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

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 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 instead; see 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 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.

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.

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

Code

Implementation
Tooltip Props

Common Examples

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

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>
  );
}

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

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.

boolean

default:"false"

number

default:"100"

Delay in milliseconds before showing the tooltip.

boolean

default:"false"

boolean

default:"false"

Placement[]

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

number

default:"5"

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

(open: boolean) => void

boolean

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

boolean

Changes interaction to use hover instead of focus.

default:"top"

Concepts & Guidelines

Anvil2

Resources

Tooltip - Web

Anatomy