Tooltip

A tooltip component for displaying contextual labels on hover and focus

Anatomy

<Tooltip.Provider>
  <Tooltip.Root>
    <Tooltip.Trigger>Hover me</Tooltip.Trigger>
    <Tooltip.Popup>
      <Tooltip.Arrow />
      <Tooltip.Label>Label text</Tooltip.Label>
      <Tooltip.Shortcut>K</Tooltip.Shortcut>
    </Tooltip.Popup>
  </Tooltip.Root>
</Tooltip.Provider>

<media-tooltip-group>
  <button commandfor="my-tooltip">Hover me</button>
  <media-tooltip id="my-tooltip">
    <media-tooltip-label>Label text</media-tooltip-label>
    <media-tooltip-shortcut>K</media-tooltip-shortcut>
  </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 the preferred placement relative to the trigger. When the preferred side overflows the positioning boundary, the tooltip uses the opposite side if it has more space. Positioning uses CSS Anchor Positioning where supported, with a JavaScript measurement fallback.

The component is composed from six parts: Root manages state and context, Trigger renders a button that activates the tooltip, Popup contains the label content, Label renders the tooltip body, Shortcut renders an optional keyboard hint, and Arrow renders a decorative pointer. Wrap multiple tooltips in a Tooltip.Provider to coordinate open/close timing across a group — once a tooltip becomes visible, adjacent tooltips open instantly within the timeout window, skipping the normal delay.

Styling

Use CSS custom properties for positioning offsets:

React renders standard DOM elements. Add a className to style them:

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

Style based on open state, rendered side, and transition phases. data-side reflects the rendered side and can differ from the preferred side prop after collision handling:

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;
}

.tooltip-popup[data-open] {
  display: block;
}
.tooltip-popup[data-starting-style] {
  opacity: 0;
}
.tooltip-popup[data-ending-style] {
  opacity: 0;
}
.tooltip-popup[data-side="top"] {
  transform-origin: bottom center;
}
.tooltip-popup[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

import { Tooltip } from '@videojs/react';

export default function BasicUsage() {
  return (
    <div className="demo">
      <Tooltip.Root>
        <Tooltip.Trigger className="trigger">Hover me</Tooltip.Trigger>
        <Tooltip.Popup className="media-tooltip">
          <Tooltip.Arrow className="arrow" />
          <Tooltip.Label>Tooltip content</Tooltip.Label>
        </Tooltip.Popup>
      </Tooltip.Root>
    </div>
  );
}

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

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

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

.arrow {
  fill: rgba(0, 0, 0, 0.85);
}

<div class="demo">
    <button type="button" commandfor="tooltip-demo" class="trigger">Hover me</button>
    <media-tooltip id="tooltip-demo" class="media-tooltip">
        Tooltip content
    </media-tooltip>
</div>

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

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

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

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

Grouping

Wrap multiple tooltips in a Tooltip.Provider to share a delay group. Once a tooltip becomes visible, adjacent tooltips open instantly within the timeout window, skipping the normal delay.

import { Tooltip } from '@videojs/react';

export default function Grouping() {
  return (
    <div className="demo">
      <Tooltip.Provider>
        <Tooltip.Root>
          <Tooltip.Trigger className="trigger">Play</Tooltip.Trigger>
          <Tooltip.Popup className="media-tooltip">
            <Tooltip.Arrow className="arrow" />
            <Tooltip.Label>Play video</Tooltip.Label>
          </Tooltip.Popup>
        </Tooltip.Root>
        <Tooltip.Root>
          <Tooltip.Trigger className="trigger">Mute</Tooltip.Trigger>
          <Tooltip.Popup className="media-tooltip">
            <Tooltip.Arrow className="arrow" />
            <Tooltip.Label>Mute audio</Tooltip.Label>
          </Tooltip.Popup>
        </Tooltip.Root>
        <Tooltip.Root>
          <Tooltip.Trigger className="trigger">Fullscreen</Tooltip.Trigger>
          <Tooltip.Popup className="media-tooltip">
            <Tooltip.Arrow className="arrow" />
            <Tooltip.Label>Enter fullscreen</Tooltip.Label>
          </Tooltip.Popup>
        </Tooltip.Root>
      </Tooltip.Provider>
    </div>
  );
}

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

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

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

.arrow {
  fill: rgba(0, 0, 0, 0.85);
}

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="demo">
    <button type="button" commandfor="tooltip-play" class="trigger">Play</button>
    <media-tooltip id="tooltip-play" class="media-tooltip">Play video</media-tooltip>

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

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

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

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

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

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

API Reference

Provider

Props

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

Root

Props

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

State

State is accessible via the render, className, and style props.

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 Preferred side of the trigger for the tooltip.
`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 the rendered side of the tooltip after collision handling.
`data-align`	`'start' \| 'center' \| 'end'`
Description Indicates how the tooltip is aligned relative to the specified side.

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-boundary-offset`
Description Minimum distance between the popup and the positioning boundary.
`--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.

Trigger

Element that triggers the tooltip on hover and focus. Renders a <button> element.

Data attributes

Attribute	Type	Details
`data-open`
Description Present when the tooltip is open.
`data-side`	`'top' \| 'bottom' \| 'left' \| 'right'`
Description Indicates the rendered side of the tooltip after collision handling.
`data-align`	`'start' \| 'center' \| 'end'`
Description Indicates how the tooltip is aligned relative to the specified side.

Container for the tooltip content. Positioned relative to the trigger using CSS anchor positioning with a JavaScript fallback.

Attribute	Type	Details
`data-open`
Description Present when the tooltip is open.
`data-side`	`'top' \| 'bottom' \| 'left' \| 'right'`
Description Indicates the rendered side of the tooltip after collision handling.
`data-align`	`'start' \| 'center' \| 'end'`
Description Indicates how the tooltip is aligned relative to the specified side.

Label

Tooltip body label; defaults to context content.label from the linked trigger.

Data attributes

Attribute	Type	Details
`data-open`
Description Present when the tooltip is open.
`data-side`	`'top' \| 'bottom' \| 'left' \| 'right'`
Description Indicates the rendered side of the tooltip after collision handling.
`data-align`	`'start' \| 'center' \| 'end'`
Description Indicates how the tooltip is aligned relative to the specified side.

Shortcut

Keyboard shortcut hint; apply skin className (CSS: media-tooltip__kbd; Tailwind: popup.tooltipShortcut).

Data attributes

Attribute	Type	Details
`data-open`
Description Present when the tooltip is open.
`data-side`	`'top' \| 'bottom' \| 'left' \| 'right'`
Description Indicates the rendered side of the tooltip after collision handling.
`data-align`	`'start' \| 'center' \| 'end'`
Description Indicates how the tooltip is aligned relative to the specified side.

Arrow

Decorative arrow pointing from the tooltip toward the trigger. Hidden from assistive technology.

Anatomy

Behavior

Styling

Accessibility

Examples

Basic Usage

Grouping

API Reference

Providermedia-tooltip-group

Props

Rootmedia-tooltip

Props

State

Data attributes

CSS custom properties

TriggerTrigger

Data attributes

PopupPopup

Data attributes

Labelmedia-tooltip-label

Data attributes

Shortcutmedia-tooltip-shortcut

Data attributes

ArrowArrow

Provider

Root

Trigger

Popup

Label

Shortcut

Arrow