Tooltip

WHEN TO USE

• A control's meaning is not fully carried by its visible label — most often an icon-only button in a dense toolbar.
• You are naming something the user can already see, briefly. A tooltip supplements; it does not explain.
• The trigger is not itself focusable — a plain <span slot="trigger"> — which is the usage the component's own focus handling is written for.

WHEN NOT TO USE

• The information is required to complete a field. Persistent helper text under the input is read by everyone, including people who never hover.USE INPUT →
• The content is more than a phrase, or contains its own controls. A tooltip that has to be read is the wrong container for it.USE POPOVER →
• You are reporting the result of an action.USE TOAST →
• The content is a decision the user must make before continuing.USE DIALOG →

DO

• Slot a non-focusable trigger — a <span> or an icon — and let the component supply the tab stop. That is the documented usage, and the case where the description is wired to the element that actually receives focus.
• Give the trigger control its own accessible name when it IS focusable. Do not let the tooltip be the only place the name exists.
• Use isDynamic when the tooltip sits near a viewport edge; it repositions based on where the trigger is rather than always honouring position.
• Set isInteractive only when the tooltip's content genuinely has to be reached with the pointer, and accept that a tooltip you can move into is harder to dismiss.

DON’T

• Don't put information in a tooltip that exists nowhere else. It is unavailable to touch users, to anyone who does not hover, and — when the trigger is a focusable control — to screen-reader users too.
• Don't assume aria-describedby reaches your slotted control. The attribute is rendered on the tooltip's own internal trigger wrapper, not on what you slot into it, and the description cannot be projected across the shadow boundary onto a focusable slotted element.
• Don't slot an <al-button> and expect both a tab stop on the wrapper and the tooltip association. When the slotted trigger has its own focusable element the wrapper deliberately drops its tabindex — it used to produce two tab stops for one control — so the focused control is the button, which carries no reference to the tooltip.
• Don't use a tooltip on a touch-primary surface as the only affordance. There is no hover there to trigger it.