`<bmx-tooltip>`

A short description of the thing beside it, shown on hover and on focus.

10 properties · 1 events · 2 methods · 2 parts

Example

Publish

Makes this visible to everyone in the workspace.

Archive

Hides it from the list without deleting anything. You can undo this for thirty days.

Slow to open

A longer delay, for a control whose meaning is already obvious.

Hover one and then move the pointer into the tooltip — it stays, which WCAG 2.2 SC 1.4.13 requires and most hand-rolled tooltips do not do. Press Escape while it is open and it goes without the pointer moving, and does not spring back until the pointer has been somewhere else. Tab to a button and the tooltip opens at once: a keyboard user has arrived deliberately and should not be made to wait.

The description is on the button before any of that happens. aria-describedby is written once and left there, because accessible-description computation reads through a hidden element on purpose — so a screen-reader user hears it on arrival rather than only if their pointer happens to rest somewhere first.

Show markup

<div class="row">
  <bmx-button id="ex-tip-publish" variant="outline" tone="neutral">Publish</bmx-button>
  <bmx-tooltip for="#ex-tip-publish">Makes this visible to everyone in the workspace.</bmx-tooltip>

  <bmx-button id="ex-tip-archive" variant="outline" tone="neutral">Archive</bmx-button>
  <bmx-tooltip for="#ex-tip-archive" placement="bottom">Hides it from the list without deleting anything. You can undo this for thirty days.</bmx-tooltip>

  <bmx-button id="ex-tip-slow" variant="outline" tone="neutral">Slow to open</bmx-button>
  <bmx-tooltip for="#ex-tip-slow" open-delay="900">A longer delay, for a control whose meaning is already obvious.</bmx-tooltip>
</div>

<div class="row">
  <span class="note">
    Hover one and then move the pointer <em>into</em> the tooltip — it stays, which WCAG 2.2 SC 1.4.13 requires and most
    hand-rolled tooltips do not do. Press <kbd>Escape</kbd> while it is open and it goes without the pointer moving, and
    does not spring back until the pointer has been somewhere else. Tab to a button and the tooltip opens at once: a
    keyboard user has arrived deliberately and should not be made to wait.
  </span>
</div>

<div class="row" style="margin-block-start: 1rem">
  <span class="note">
    The description is on the button before any of that happens. <code>aria-describedby</code> is written once and left
    there, because accessible-description computation reads through a hidden element on purpose — so a screen-reader
    user hears it on arrival rather than only if their pointer happens to rest somewhere first.
  </span>
</div>

<bmx-button id="publish">Publish</bmx-button>
<bmx-tooltip for="#publish">Makes this visible to everyone in the workspace.</bmx-tooltip>

A TOOLTIP DESCRIBES; A POPOVER CONTAINS

This is the distinction the whole pair turns on, and it decides everything else. A tooltip is a description of its anchor: it holds a few words, it has no interactive content, it never takes focus, and it reaches a screen reader through aria-describedby on the anchor rather than by being visited. Anything a user must reach - a link, a button, a form - belongs in bmx-popover, which is a small non-modal dialog that focus moves into.

Getting this pair the wrong way round is the single most common accessibility defect in commercial component suites: a "tooltip" holding a link is content a keyboard user can see and cannot get to. This component does not stop you - it could only reach the outermost children, which would enforce the rule at one nesting depth and silently not the next, and blanking the content area instead would take text selection with it. What it does is never take focus itself, so a tooltip holding a control is visibly a control nobody can reach, rather than an accessibility failure that looks fine.

WCAG 2.2 SC 1.4.13, WHICH IS THREE RULES

Dismissible - Escape hides it without the pointer moving, and it does not spring back under a pointer that stayed where it was. Hoverable - the pointer can travel into the tooltip to read it, which is what the close delay is for; it is the time the pointer takes to cross the gap, not a fade-out. Persistent - it never disappears on a timer of its own. The rules are src/core/hover-intent.ts, tested without a browser, and the reason they are arithmetic is that they argue with each other in every ordering a pointer can produce.

THE DESCRIPTION IS THERE BEFORE THE TOOLTIP IS

aria-describedby is written on the anchor once and left there, rather than added when the tooltip opens. Accessible-description computation deliberately reads through a hidden referenced element, so a screen-reader user hears the description the moment they reach the anchor - without a visual tooltip having to open first, and without this component having to guess when their software would like to know.

Properties

Property	Attribute	Type	Default	Description
`closeDelay`	`close-delay`	`number`	`150`	How long it stays after the last thing letting go. The bridge the pointer crosses.
`content`	`content`	`string`	—	The text. Use the default slot instead when it needs markup.
`disabled`	`disabled`	`boolean`	`false`	Nothing opens it, and the description stays on the anchor.
`distance`	`distance`	`number`	`8`	Gap between the anchor and the box, in pixels.
`for`	`for`	`string \| HTMLElement`	—	What it describes: a selector, or the element itself. Left off, the anchor is the element immediately before this one, which is what the markup above already reads like. A selector is resolved against this component's own root first, so a tooltip inside somebody else's shadow tree can still name its anchor.
`hoverable`	`hoverable`	`boolean`	`true`	Whether the pointer may move into the tooltip without closing it. On, because SC 1.4.13 requires it. Turning it off makes a long tooltip unreadable to anyone who cannot read it in one glance.
`open`	`open`	`boolean`	`false`	Whether it is on screen. Settable, for a tour or a validation hint.
`openDelay`	`open-delay`	`number`	`400`	How long the pointer rests before it opens, in milliseconds.
`placement`	`placement`	`BmxPlacement`	`'top'`	Where it prefers to sit. It flips when there is no room.
`trigger`	`trigger`	`BmxHoverTrigger`	`'both'`	How it may be opened.

Events

Event	Detail	Description
`bmxOpenChange`	`boolean`	Fired when it opens or closes, with `true` or `false`.

Methods

Method	Signature	Description
`hideTooltip`	`hideTooltip() => Promise<void>`	Hide it now.
`showTooltip`	`showTooltip() => Promise<void>`	Show it now, whatever the delays say.

Slots

Slot	Description
`(default)`	The tooltip's content, when it is more than the `content` property.

CSS shadow parts

Part	Description
`arrow`	The pointer drawn against the anchor.
`surface`	The floating box.

CSS custom properties

Property	Description
`--bmx-tooltip-arrow-size`	The pointer's size. Set it to 0 for no pointer at all.
`--bmx-tooltip-background`	The box's background.
`--bmx-tooltip-border-color`	Its border. Carries the shape under forced colours.
`--bmx-tooltip-color`	Its text colour.
`--bmx-tooltip-font-size`	The text size.
`--bmx-tooltip-max-inline-size`	How wide it may grow before wrapping. A tooltip that runs the width of the window is unreadable.
`--bmx-tooltip-padding-block`	Space above and below the text.
`--bmx-tooltip-padding-inline`	Space either side of it.
`--bmx-tooltip-radius`	Its corner radius.
`--bmx-tooltip-shadow`	The shadow under the box.