Tooltip

A tooltip shows a short hint about an element when you hover over it or move keyboard focus to it. It is for extra information that is nice to have, but not needed to get the task done. The most common case: naming an icon button, or the full date behind a relative time like 5 minutes ago.

Use a tooltip for:

• Naming an icon without a visible label
• Extra detail behind a short value, like the full date behind a relative time

Don't use a tooltip for:

• Anything essential, like instructions or an error. Tooltips only show on hover and keyboard focus, and on a touch screen they are hard or impossible to reach. Put it on the screen itself, as text or an alert.
• Links, buttons, or other interactive content. People can't reach them.

1. Target: the element the tooltip is about, pointed to with for
2. Body: the surface with the tooltip text. There is no arrow by default.

The tooltip sits above its target by default. It can be placed on another side, like below or to the right. It flips to the other side, or shifts, when there is no room.

• Hover: the tooltip shows 350ms after the pointer enters the target, and hides 150ms after it leaves. Moving the pointer from the target onto the tooltip keeps it open.
• Focus: the tooltip shows when the target gets focus, and hides when it loses focus.
• Dismiss: Escape hides an open tooltip. So does a press anywhere outside the target.
• Disabled: a disabled tooltip doesn't show.
• The tooltip appears and disappears without animation.
• Text wraps at 30 characters wide.

• Keep it to one short sentence, or a few words.
• Never put anything essential in a tooltip, like instructions or an error.
• No links, buttons, or other interactive content.

The target needs to be focusable for keyboard users to see the tooltip. An icon is not focusable on its own.

The tooltip text becomes the name of its target. That works well for an icon without a label. On a target with a visible label, screen readers read the tooltip text instead of that label.

• The demos on this page add tabindex="0" to an icon to make it focusable.
• The tooltip adds its own id to the aria-labelledby of its target. That makes the tooltip text the accessible name of the target, which works well for an icon without a label. On a target with a visible label, screen readers read the tooltip text instead of that label.
• The tooltip body has no role of its own.

• Alert: for information that people need
• Button: a common target of a tooltip

The element is <ha-tooltip>. It is based on the Web Awesome tooltip. Give the target an id, and point the tooltip at it with for:

<ha-svg-icon id="help-icon" path="..."></ha-svg-icon>
<ha-tooltip for="help-icon">Measured every 30 seconds</ha-tooltip>

• for: the id of the target element. The target must be in the same document or shadow root.
• placement: top (default), bottom, left, right, or one of those with -start or -end, like top-start.
• distance: the gap between the tooltip and the target, in pixels. Defaults to 8.
• show-delay: milliseconds before showing. Defaults to 350.
• hide-delay: milliseconds before hiding. Defaults to 150.
• trigger: what opens the tooltip. Defaults to hover focus. Also accepts click and manual.
• disabled: stops the tooltip from showing.
• open: shows the tooltip.

• Default: the tooltip text.

• --ha-tooltip-background-color: defaults to var(--ha-color-surface-default).
• --ha-tooltip-text-color: defaults to var(--primary-text-color).
• --ha-tooltip-font-size: defaults to var(--ha-font-size-m).
• --ha-tooltip-line-height: defaults to var(--ha-line-height-condensed).
• --ha-tooltip-border-radius: defaults to var(--ha-border-radius-md).
• --ha-tooltip-arrow-size: defaults to 0px, so there is no arrow.
• --ha-tooltip-box-shadow: defaults to var(--ha-box-shadow-m).
• --ha-tooltip-animation-duration: defaults to 0, so it appears without animation.

ha-tooltip also sets --ha-tooltip-font-family, --ha-tooltip-font-weight, and --ha-tooltip-padding on the Web Awesome tooltip. The Web Awesome version in use does not read the variables they feed, so they have no visible effect.

Source: src/components/ha-tooltip.ts