media-tooltip

A tooltip component for displaying contextual labels on hover and focus

Anatomy

<media-tooltip-group>
  <button commandfor="my-tooltip">Hover me</button>
  <media-tooltip id="my-tooltip">Label text</media-tooltip>
</media-tooltip-group>

Behavior

Displays a short label anchored to a trigger element. Opens after a configurable delay (default 600ms) on hover or immediately on focus. Closes when the pointer leaves or focus moves away, with an optional closeDelay.

The side and align props control placement relative to the trigger. Positioning uses CSS Anchor Positioning where supported, with a JavaScript measurement fallback.

The <media-tooltip> element is the popup itself. Link it to a trigger using the commandfor attribute on any button, pointing to the tooltip’s id. The element discovers its trigger automatically and manages open/close state, ARIA attributes, and positioning. Wrap tooltip trigger/popup pairs in <media-tooltip-group> to coordinate timing — the group’s delay, close-delay, and timeout attributes control shared timing for all contained tooltips.

Styling

Use CSS custom properties for positioning offsets:

media-tooltip {
  --media-tooltip-side-offset: 8px;
  --media-tooltip-align-offset: 0px;
}

Style based on open state and transition phases:

media-tooltip[data-open] {
  display: block;
}
media-tooltip[data-starting-style] {
  opacity: 0;
}
media-tooltip[data-ending-style] {
  opacity: 0;
}
media-tooltip[data-side="top"] {
  transform-origin: bottom center;
}
media-tooltip[data-side="bottom"] {
  transform-origin: top center;
}

Accessibility

The trigger receives aria-describedby pointing to the popup when open. The popup renders with role="tooltip" and popover="manual". Tooltips open on focus and close when focus leaves, ensuring keyboard-only users can access the label.

Examples

Basic Usage

<div class="html-tooltip-basic">
    <button type="button" commandfor="tooltip-demo" class="html-tooltip-basic__trigger">Hover me</button>
    <media-tooltip id="tooltip-demo" class="html-tooltip-basic__popup">
        Tooltip content
    </media-tooltip>
</div>

.html-tooltip-basic {
  display: flex;
  align-items: center;
  justify-content: center;
  padding: 40px 24px;
}

.html-tooltip-basic__trigger {
  padding: 6px 16px;
  background: rgba(255, 255, 255, 0.7);
  backdrop-filter: blur(10px);
  color: black;
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  cursor: pointer;
}

.html-tooltip-basic__popup {
  --media-tooltip-side-offset: 8px;
  background: rgba(0, 0, 0, 0.85);
  backdrop-filter: blur(10px);
  color: white;
  border-radius: 6px;
  padding: 4px 10px;
  font-size: 13px;
  white-space: nowrap;
  pointer-events: none;
}

import '@videojs/html/ui/tooltip';

Grouping

Wrap tooltip trigger/popup pairs in <media-tooltip-group> to coordinate timing. The group’s delay, close-delay, and timeout attributes control shared timing for all contained tooltips.

<media-tooltip-group class="html-tooltip-grouping">
    <button type="button" commandfor="tooltip-play" class="html-tooltip-grouping__trigger">Play</button>
    <media-tooltip id="tooltip-play" class="html-tooltip-grouping__popup">Play video</media-tooltip>

    <button type="button" commandfor="tooltip-mute" class="html-tooltip-grouping__trigger">Mute</button>
    <media-tooltip id="tooltip-mute" class="html-tooltip-grouping__popup">Mute audio</media-tooltip>

    <button type="button" commandfor="tooltip-fullscreen" class="html-tooltip-grouping__trigger">Fullscreen</button>
    <media-tooltip id="tooltip-fullscreen" class="html-tooltip-grouping__popup">Enter fullscreen</media-tooltip>
</media-tooltip-group>

.html-tooltip-grouping {
  display: flex;
  align-items: center;
  justify-content: center;
  padding: 40px 24px;
}

.html-tooltip-grouping__trigger {
  padding: 6px 16px;
  background: rgba(255, 255, 255, 0.7);
  backdrop-filter: blur(10px);
  color: black;
  border: 1px solid rgba(255, 255, 255, 0.3);
  cursor: pointer;
}

.html-tooltip-grouping__popup {
  --media-tooltip-side-offset: 8px;
  background: rgba(0, 0, 0, 0.85);
  backdrop-filter: blur(10px);
  color: white;
  border-radius: 6px;
  padding: 4px 10px;
  font-size: 13px;
  white-space: nowrap;
  pointer-events: none;
}

import '@videojs/html/ui/tooltip';
import '@videojs/html/ui/tooltip-group';

API Reference

media-tooltip-group

Props

Prop	Type	Default
`closeDelay`	`number`	`—`
Attribute `close-delay` Description Default close delay in ms for tooltips in this group.
`delay`	`number`	`—`
Attribute `delay` Description Default open delay in ms for tooltips in this group.
`timeout`	`number`	`—`
Attribute `timeout` Description Duration in ms after a tooltip closes during which the next tooltip opens instantly.

media-tooltip

Props

Prop	Type	Default
`align`	`'start' \| 'center' \| 'end'`	`'center'`
Attribute `align` Description Alignment of the tooltip along the trigger's edge.
`closeDelay`	`number`	`0`
Attribute `close-delay` Description Delay in ms before closing after pointer leaves.
`defaultOpen`	`boolean`	`false`
Attribute `default-open` Description Initial open state for uncontrolled usage.
`delay`	`number`	`600`
Attribute `delay` Description Delay in ms before opening on hover.
`disabled`	`boolean`	`false`
Attribute `disabled` Description When true, the tooltip is disabled and will not open.
`disableHoverablePopup`	`boolean`	`true`
Attribute `disable-hoverable-popup` Description When true, hovering the popup does not keep it open.
`open`	`boolean`	`false`
Attribute `open` Description Controlled open state.
`side`	`'top' \| 'bottom' \| 'left' \| 'right'`	`'top'`
Attribute `side` Description Which side of the trigger the tooltip appears on.

State

State is reflected as data attributes for CSS styling.

Property	Type	Details
`open`	`boolean`
Description Whether the tooltip is currently visible.
`status`	`'idle' \| 'starting' \| 'ending'`
Description Current phase of the transition lifecycle.
`side`	`'top' \| 'bottom' \| 'left' \| 'right'`
Description Which side of the trigger the tooltip is positioned on.
`align`	`'start' \| 'center' \| 'end'`
Description How the tooltip is aligned relative to the specified side.
`transitionStarting`	`boolean`
Description Whether the open transition is in progress.
`transitionEnding`	`boolean`
Description Whether the close transition is in progress.

Data attributes

Attribute	Type	Details
`data-open`
Description Present when the tooltip is open.
`data-side`	`'top' \| 'bottom' \| 'left' \| 'right'`
Description Indicates which side the tooltip is positioned relative to the trigger.
`data-align`	`'start' \| 'center' \| 'end'`
Description Indicates how the tooltip is aligned relative to the specified side.
`data-starting-style`
Description Present when the open transition is in progress.
`data-ending-style`
Description Present when the close transition is in progress.

CSS custom properties

Variable	Details
`--media-tooltip-side-offset`
Description Distance between the popup and the trigger along the side axis.
`--media-tooltip-align-offset`
Description Distance between the popup and the trigger along the alignment axis.
`--media-tooltip-anchor-width`
Description The anchor element's width.
`--media-tooltip-anchor-height`
Description The anchor element's height.
`--media-tooltip-available-width`
Description Available width between the trigger and the boundary edge.
`--media-tooltip-available-height`
Description Available height between the trigger and the boundary edge.