> Markdown version of [Tooltip](https://vaadin.com/docs/next/components/tooltip). Section index: [llms.txt](https://vaadin.com/docs/next/components/llms.txt)

# Tooltip

Tooltips are small pop-ups for providing additional information about other UI elements. A tooltip for an element becomes visible when the user hovers the mouse pointer over the element or when the element receives keyboard focus.

**Lit** — `tooltip-basic.ts`

```html
<vaadin-text-field placeholder="Search">
  <vaadin-icon slot="prefix" icon="lumo:search"></vaadin-icon>
  <vaadin-tooltip slot="tooltip" text="Wrap in “quotes” for exact phrase"></vaadin-tooltip>
</vaadin-text-field>
```

**Flow** — `TooltipBasic.java`

```java
TextField textField = new TextField();
textField.setPlaceholder("Search");
textField.setPrefixComponent(new Icon("lumo", "search"));
textField.setTooltipText("Wrap in “quotes” for exact phrase");
add(textField);
```

**React** — `tooltip-basic.tsx`

```tsx
<TextField placeholder="Search">
  <Icon icon="lumo:search" slot="prefix" />
  <Tooltip slot="tooltip" text="Wrap in “quotes” for exact phrase" />
</TextField>
```

Tooltips only support plain text content. They aren’t focusable and can’t contain interactive elements.

## <a id="other-ui-elements"></a>Other UI Elements

Tooltips can be displayed for UI elements that lack a dedicated tooltip API. Proper accessibility, however, for these can’t be guaranteed.

**Lit** — `tooltip-html-element.ts`

```html
<h2 id="heading">Heading with tooltip</h2>
<vaadin-tooltip for="heading" text="This is a tooltip" position="top-start"></vaadin-tooltip>
```

**Flow** — `TooltipHtmlElement.java`

```java
H2 heading = new H2("Heading with tooltip");
Tooltip tooltip = Tooltip.forComponent(heading)
        .withText("This is a tooltip")
        .withPosition(Tooltip.TooltipPosition.TOP_START);
add(heading);
```

**React** — `tooltip-html-element.tsx`

```tsx
<h2 id="heading">Heading with tooltip</h2>
<Tooltip for="heading" text="This is a tooltip" position="top-start" />
```

The [Grid](https://vaadin.com/docs/next/components/grid.md#tooltips) and [Menu Bar](https://vaadin.com/docs/next/components/menu-bar.md#tooltips) components have dedicated APIs for configuring tooltips.

## <a id="positioning"></a>Positioning

The default positioning of the tooltip in relation to the target element can be overridden. This can be useful for optimizing where the tooltip is rendered, to avoid overlaying other important UI elements, or for purely aesthetic reasons.

**Lit** — `tooltip-positioning.ts`

```html
<vaadin-side-nav-item path="/dashboard">
  <vaadin-icon icon="vaadin:dashboard" slot="prefix"></vaadin-icon>
  <vaadin-tooltip slot="tooltip" text="Dashboard" position="end"></vaadin-tooltip>
</vaadin-side-nav-item>
```

**Flow** — `TooltipPositioning.java`

```java
SideNavItem item = new SideNavItem(viewName, path, viewIcon.create());
item.setTooltipText(viewName).withPosition(TooltipPosition.END);
```

**React** — `tooltip-positioning.tsx`

```tsx
<SideNavItem path="/dashboard">
  <Icon icon="vaadin:dashboard" slot="prefix" />
  <Tooltip slot="tooltip" text="Dashboard" position="end" />
</SideNavItem>
```

The distance between the tooltip and the target element can also be customized by setting the following CSS properties on the tooltip:

- `--vaadin-tooltip-offset-top`

- `--vaadin-tooltip-offset-bottom`

- `--vaadin-tooltip-offset-start`

- `--vaadin-tooltip-offset-end`

## <a id="configuring-delays"></a>Configuring Delays

The delay before tooltips appear can be configured separately for hover and keyboard focus. The delay before tooltips disappear — when the pointer leaves the target element — can also be configured separately. On blur, though, the tooltip is closed immediately to avoid confusion when focusing another element.

**Flow**

```java
import com.vaadin.flow.component.shared.TooltipConfiguration;

// Global delay configuration:
TooltipConfiguration.setDefaultFocusDelay(2000);
TooltipConfiguration.setDefaultHoverDelay(1000);
TooltipConfiguration.setDefaultHideDelay(1000);

// Overriding delays for a particular component’s tooltip:
button.setTooltipText("Home").withHoverDelay(500);
```

**Lit**

```typescript
import { Tooltip } from '@vaadin/tooltip';

// Global delay configuration:
Tooltip.setDefaultFocusDelay(2000);
Tooltip.setDefaultHoverDelay(1000);
Tooltip.setDefaultHideDelay(1000);

// Overriding delays for a particular component’s tooltip:
<vaadin-button>
  Click me
  <vaadin-tooltip .hoverDelay=${500} slot="tooltip" text="Home"></vaadin-tooltip>
</vaadin-button>
```

**React**

```tsx
import { Tooltip } from '@vaadin/tooltip';

// Global delay configuration:
Tooltip.setDefaultFocusDelay(2000);
Tooltip.setDefaultHoverDelay(1000);
Tooltip.setDefaultHideDelay(1000);

// Overriding delays for a particular component’s tooltip:
<Button>
  Click me
  <Tooltip hoverDelay={500} slot="tooltip" text="Home" />
</Button>
```

## <a id="triggering-manually"></a>Triggering Manually

Tooltips can be configured not to appear automatically on hover or keyboard focus, but instead be programmatically triggered only. This can be used to create so-called, *toggletips* — tooltips that can be manually displayed and hidden by the user.

**Lit** — `tooltip-manual.ts`

```html
<vaadin-tooltip
  slot="tooltip"
  text="Wrap in “quotes” for exact phrase"
  manual
  .opened="${this.tooltipOpened}"
></vaadin-tooltip>
<vaadin-button
  slot="suffix"
  theme="tertiary"
  style="padding: 0; border: 0; min-width: 0; height: 1.25rem;"
  @click="${() => {
    this.tooltipOpened = !this.tooltipOpened;
  }}"
>
  <vaadin-icon icon="vaadin:info-circle"></vaadin-icon>
</vaadin-button>
```

**Flow** — `TooltipManual.java`

```java
textField.setTooltipText("Wrap in “quotes” for exact phrase");
Tooltip tooltip = textField.getTooltip().withManual(true);
button.addClickListener(event -> {
    tooltip.setOpened(!tooltip.isOpened());
});
```

**React** — `tooltip-manual.tsx`

```tsx
<TextField placeholder="Search">
  <Icon slot="prefix" icon="lumo:search" />
  <Tooltip
    slot="tooltip"
    text="Wrap in “quotes” for exact phrase"
    manual
    opened={tooltipOpened.value}
  />
  <Button
    slot="suffix"
    theme="tertiary"
    style={{ border: 0, padding: 0, minWidth: 0, height: '1.25rem' }}
    onClick={() => {
      tooltipOpened.value = !tooltipOpened.value;
    }}
  >
    <Icon icon="vaadin:info-circle" />
  </Button>
</TextField>
```

## <a id="markdown"></a>Markdown (since V25.0)

Tooltip can be configured to render its text content as Markdown. This allows using simple formatting such as bold or italic text. By default, this feature is not active and the tooltip content is rendered as plain text.

**Flow**

```java
// For components that implement HasTooltip:
button.setTooltipMarkdown("**Bold** _Italic_ `Code`");

// For other components:
Tooltip.forComponent(header).setMarkdown("**Bold** _Italic_ `Code`");
```

**Lit**

```html
<vaadin-button>
  Click me
  <vaadin-tooltip markdown slot="tooltip" text="**Bold** _Italic_ `Code`"></vaadin-tooltip>
</vaadin-button>
```

**React**

```tsx
<Button>
  Click me
  <Tooltip markdown slot="tooltip" text="**Bold** _Italic_ `Code`" />
</Button>
```

> **Note:** Using Markdown is discouraged if accessibility of the tooltip content is essential, as semantics of the rendered HTML content (headers, lists, …​) will not be conveyed to assistive technologies. Likewise, any interactive content such as links may not be accessible. For more complex or interactive content, consider using a [Popover](https://vaadin.com/docs/next/components/popover.md) instead.

## <a id="accessibility"></a>Accessibility

Tooltips are semantically associated with their target elements by default using the [`aria-describedby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) attribute, and are announced by screen readers when the element gains keyboard focus.

However, tooltips on elements without dedicated tooltip APIs can’t be guaranteed to be announced correctly. This is because the announcement of `aria-describedby` attributes depends on the HTML element’s type and the `role` attribute. It also varies between different screen readers. Testing with screen readers is useful to ensure the accessibility of tooltips on these elements.

The tooltip feature currently doesn’t support triggering via long press on touch-screen devices.

Keep in mind that Vaadin components and other UI elements don’t, by default, imply the presence of tooltips in any way. This might make them difficult for users to discover.

In general, visible labels are always preferable to tooltips. A separately defined invisible [`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute usually provides better accessibility than a tooltip.

### <a id="aria-link-mode"></a>ARIA Link Mode (since V25.2)

The ARIA attribute used to associate the tooltip with its target element can be configured. The following modes are available:

- `aria-describedby`

  Links the tooltip as a *description* of the target. This is the default mode, and the appropriate one when the tooltip provides supplementary information about an element that already has an accessible name, such as a labeled input field.

- `aria-labelledby`

  Links the tooltip as the *accessible name* of the target. Use this mode when the tooltip text acts as the target’s label, such as on icon-only buttons that have no visible label or `aria-label` of their own.

- `none`

  Doesn’t apply any ARIA attribute to the target. Use this mode when the tooltip content is already exposed to assistive technologies by other means, to avoid redundant announcements.

**Flow**

```java
// For components that implement HasTooltip:
button.setTooltipText("Search");
button.getTooltip().setAriaLinkMode(Tooltip.AriaLinkMode.ARIA_LABELLED_BY);

// For other components:
Tooltip.forComponent(icon)
        .withText("Search")
        .withAriaLinkMode(Tooltip.AriaLinkMode.ARIA_LABELLED_BY);
```

**Lit**

```html
<vaadin-button theme="icon">
  <vaadin-icon icon="vaadin:search"></vaadin-icon>
  <vaadin-tooltip slot="tooltip" text="Search" aria-link-mode="aria-labelledby"></vaadin-tooltip>
</vaadin-button>
```

**React**

```tsx
<Button theme="icon">
  <Icon icon="vaadin:search" />
  <Tooltip slot="tooltip" text="Search" ariaLinkMode="aria-labelledby" />
</Button>
```

## <a id="best-practices"></a>Best Practices

Tooltips should be used only to provide additional information, not for mission-critical information. They’re not a replacement for visible labels on input fields.

On input field components, tooltips should be considered a last resort if neither the label — not the helper — nor the placeholder text can be used to provide the necessary information.

## <a id="related-components"></a>Related Components

| Component                                                     | Usage recommendations                                                 |
| ------------------------------------------------------------- | --------------------------------------------------------------------- |
| [Popover](https://vaadin.com/docs/next/components/popover.md) | A generic overlay whose position is anchored to an element in the UI. |