Tooltip

A tooltip is a small overlay describing the element it points at. It opens on hover and on focus, and it closes on its own as soon as either leaves.

The trigger is yours. trigger takes any element and sets a ref on it; iconTrigger wraps an icon in a div first. The arrow does the pointing, and hideArrow removes it — after which position is all the reader has.

portal decides where the overlay is rendered. It defaults to rendering in a portal at the end of the document, which is what keeps a tooltip from being clipped; set it to false inside a Modal or anything else that establishes its own stacking context, and use zIndex where the tooltip comes out under something.

Use a tooltip for something the reader can do without: what an icon button means, what an abbreviation stands for, what a truncated cell says in full. Underline the word where the trigger is a term in running text, since a phrase with no affordance is a tooltip nobody finds.

Tooltips work because they are rare. A screen full of them is a screen nobody hovers, and the one that mattered is indistinguishable from the twelve that repeated the label.

A tooltip is information the reader can miss, and on a touch screen there is no hover, so a tooltip that only opens that way never opens. Instructions needed to finish a task go in the interface: helper text under the field for a form, a Modal for guidance long enough to need its own focus.

disabled stops the tooltip rendering at all, which is the honest way to turn one off in a context that cannot show it.

It opens 300ms after the pointer arrives, 8px below the trigger. side moves it, and the delay is delayDuration. The pause is what stops a tooltip firing on every element the pointer crosses on its way somewhere else; shortening it to zero on a dense toolbar turns the whole row into flicker.

A tooltip with no renderable children renders nothing — no empty surface, no arrow. The trigger is left as it was.

The pointer can enter a tooltip; nothing in it can be used. Content with role="tooltip" is not reachable by keyboard, so a button or a link in there cannot be operated at all — not by a keyboard, and not by anyone using the tooltip the way it announces itself.

interactive defaults to true, which keeps the tooltip open while the pointer is inside it. That is so a long message can be read, not permission to put controls there — the default permits what the guidance forbids, and it is an open question with persona-web.

trigger gets a ref and nothing else: if the element you pass is not focusable on its own, the tooltip has no keyboard path in, and a reader who does not use a pointer never sees it. A <button> or a link is fine. A <span> or a bare <svg> is not.

iconTrigger is the exception, and it is why the prop exists. It wraps the icon in a focusable div, hides the icon itself from assistive tech, and takes the tooltip’s aria-label as the name for the wrapper — so an icon trigger is reachable and named, where a raw icon passed to trigger is neither.

The description wiring is not yours to do. While the tooltip is open, the trigger carries an aria-describedby pointing at the message, and the message is also rendered in a hidden node so it reaches a screen reader whichever way the reader arrives.

The surface caps at 250px wide unless maxWidth says otherwise, and it grows downward from there. A paragraph in a tooltip becomes a tall block hanging over the thing it was explaining, and the reader loses the element while reading about it.

size is sm or md, defaulting to md, and it changes the tooltip’s own type scale rather than how much it can hold. Neither size makes room for a second sentence.

Say what the element does rather than that it can be clicked. See Writing for the rest.