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

# Tooltip (since V23.3)

Tooltips are small pop-ups that can provide additional information about a UI element on hover and keyboard focus.

**TypeScript** — `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>
```

**Java** — `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);
```

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 also be displayed for UI elements that lack a dedicated tooltip API. Proper accessibility, however, can’t be guaranteed for these.

**TypeScript** — `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>
```

**Java** — `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);
```

The following components have dedicated APIs for configuring tooltips:

- [Grid](https://vaadin.com/docs/v23/components/grid.md#tooltips)

- [Menu Bar](https://vaadin.com/docs/v23/components/menu-bar.md#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 purposes.

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

```html
<vaadin-tab>
            <a tabindex="-1">
              <vaadin-icon icon="vaadin:home"></vaadin-icon>
            </a>
            <vaadin-tooltip slot="tooltip" text="Home" position="end"></vaadin-tooltip>
          </vaadin-tab>
```

**Java** — `TooltipPositioning.java`

```java
Tab tab = new Tab(link);
tab.setTooltipText(viewName).withPosition(TooltipPosition.END);
```

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, once the pointer leaves the target element, can also be configured separately. On blur, the tooltip is closed immediately to avoid confusion when focusing another element.

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

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

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

**TypeScript** — `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-inline icon"
  @click="${() => {
    this.tooltipOpened = !this.tooltipOpened;
  }}"
>
  <vaadin-icon icon="vaadin:info-circle"></vaadin-icon>
</vaadin-button>
```

**Java** — `TooltipManual.java`

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

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

Tooltips are semantically associated with their target elements 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, as 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 necessary to ensure 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 may 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 will usually provide better accessibility than a tooltip.

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

- Tooltips should only be used to provide additional information, not for mission critical information, such as 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.
