ReferenceMenus

media-volume-popover

A volume-aware popover that keeps mute available when volume level controls are unavailable

Import

import '@videojs/html/ui/volume-popover';
import '@videojs/html/ui/mute-button';
import '@videojs/html/ui/volume-slider';
import '@videojs/html/ui/slider-track';
import '@videojs/html/ui/slider-fill';
import '@videojs/html/ui/slider-thumb';

Anatomy

<media-mute-button commandfor="volume-popup"></media-mute-button>
<media-volume-popover id="volume-popup">
  <media-volume-slider></media-volume-slider>
</media-volume-popover>

Behavior

<media-volume-popover> combines popover behavior with volume availability. When volume level controls are unavailable, it closes and omits the popup while keeping the mute trigger rendered. This lets media with fixed volume keep mute control without exposing a nonfunctional slider.

The trigger can target the popup with commandfor. An immediately adjacent trigger is linked automatically when neither element has an authored ID.

Styling

The popup reflects data-availability="available" while it can render volume controls.

When it cannot, the element also receives native hidden and data-hidden.

media-volume-popover[data-open] {
  opacity: 1;
}

Accessibility

The trigger receives aria-haspopup, aria-expanded, and aria-controls while the volume popup is available. When only mute is available, the trigger keeps the mute button’s own accessible name and behavior without popup ARIA.

Examples

Basic usage

<video-player class="html-volume-popover-basic">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <div class="html-volume-popover-basic__controls">
      <media-mute-button commandfor="volume-popover-demo" class="html-volume-popover-basic__trigger">
        <span class="muted">Unmute</span>
        <span class="unmuted">Mute</span>
      </media-mute-button>
      <media-volume-popover id="volume-popover-demo" open-on-hover side="top" class="html-volume-popover-basic__popup">
        <media-volume-slider orientation="vertical" class="html-volume-popover-basic__slider">
          <media-slider-track class="html-volume-popover-basic__track">
            <media-slider-fill class="html-volume-popover-basic__fill"></media-slider-fill>
          </media-slider-track>
          <media-slider-thumb class="html-volume-popover-basic__thumb"></media-slider-thumb>
        </media-volume-slider>
      </media-volume-popover>
    </div>
  </media-container>
</video-player>

.html-volume-popover-basic media-container {
  position: relative;
  display: block;
}

.html-volume-popover-basic video {
  width: 100%;
}

.html-volume-popover-basic__controls {
  position: absolute;
  bottom: 10px;
  left: 10px;
}

.html-volume-popover-basic__trigger {
  padding: 8px 20px;
  color: black;
  cursor: pointer;
  background: rgb(255 255 255 / 70%);
  border: 1px solid rgb(255 255 255 / 30%);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}

.html-volume-popover-basic__trigger .muted,
.html-volume-popover-basic__trigger .unmuted {
  display: none;
}

.html-volume-popover-basic__trigger[data-muted] .muted,
.html-volume-popover-basic__trigger:not([data-muted]) .unmuted {
  display: inline;
}

.html-volume-popover-basic__popup {
  --media-popover-side-offset: 8px;
  width: 40px;
  height: 120px;
  padding: 12px;
  margin: 0;
  background: rgb(0 0 0 / 85%);
  border: 0;
  border-radius: 8px;
}

.html-volume-popover-basic__slider {
  position: relative;
  display: block;
  width: 16px;
  height: 96px;
  margin: auto;
  cursor: pointer;
}

.html-volume-popover-basic__track {
  position: absolute;
  top: 0;
  bottom: 0;
  left: 6px;
  width: 4px;
  background: rgb(255 255 255 / 30%);
  border-radius: 9999px;
}

.html-volume-popover-basic__fill {
  position: absolute;
  right: 0;
  bottom: 0;
  left: 0;
  height: var(--media-slider-fill);
  background: white;
  border-radius: inherit;
}

.html-volume-popover-basic__thumb {
  position: absolute;
  bottom: var(--media-slider-fill);
  left: 1px;
  width: 14px;
  height: 14px;
  background: white;
  border-radius: 50%;
  transform: translateY(50%);
}

import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/mute-button';
import '@videojs/html/ui/volume-popover';
import '@videojs/html/ui/volume-slider';
import '@videojs/html/ui/slider-track';
import '@videojs/html/ui/slider-fill';
import '@videojs/html/ui/slider-thumb';

API Reference

media-volume-popover

A volume-aware popover that keeps its adjacent mute trigger available as a fallback.

Props

Prop	Type	Default
`align`	`'start' \| 'center' \| 'end'`	—
Description Alignment of the popup along the trigger's edge.
`boundary`	`'viewport' \| 'container' \| string & {}`	—
Description Boundary used to constrain the popup position.
`closeDelay` attribute `close-delay`	`number`	—
Description Delay in ms before closing after pointer leaves.
`closeOnEscape` attribute `close-on-escape`	`boolean`	—
Description Close the popup when the Escape key is pressed.
`closeOnOutsideClick` attribute `close-on-outside-click`	`boolean`	—
Description Close the popup when clicking outside the trigger and popup.
`defaultOpen` attribute `default-open`	`boolean`	—
Description Initial open state for uncontrolled usage.
`delay`	`number`	—
Description Delay in ms before opening on hover.
`modal`	`boolean \| 'trap-focus'`	—
Description `false` (default): non-modal; background content remains interactive. `true`: modal; sets `aria-modal="true"` on the popup. `'trap-focus'`: reserved for future focus-trapping behavior.
`open`	`boolean`	—
Description Controlled open state. When set, the consumer is responsible for toggling.
`openOnHover` attribute `open-on-hover`	`boolean`	—
Description Open the popup on pointer hover instead of click.
`side`	`'top' \| 'bottom' \| 'left' \| 'right'`	—
Description Preferred side of the trigger for the popup.

State

State is reflected as data attributes for CSS styling.

Property	Type	Details
`transitionStarting`	`boolean`
Description Whether the open transition is in progress.
`transitionEnding`	`boolean`
Description Whether the close transition is in progress.
`open`	`boolean`
`status`	`'idle' \| 'starting' \| 'ending'`
`side`	`'top' \| 'bottom' \| 'left' \| 'right'`
Description Preferred side of the trigger for the popup.
`align`	`'start' \| 'center' \| 'end'`
`modal`	`boolean \| 'trap-focus'`
`availability`	`'available' \| 'unavailable' \| 'unsupp...`
Description Whether volume level controls are available. Type `'available' \| 'unavailable' \| 'unsupported'`
`hidden`	`boolean`
Description Whether the popup is hidden because volume level controls are unavailable.

Data attributes

Attribute	Type	Details
`data-open`	—
Description Present when the popover is open.
`data-side`	`'top' \| 'bottom' \| 'left' \| 'right'`
Description Indicates the rendered side after collision handling.
`data-align`	`'start' \| 'center' \| 'end'`
Description Indicates how the popup is aligned relative to its side.
`data-starting-style`	—
Description Present during the open transition.
`data-ending-style`	—
Description Present during the close transition.
`data-availability`	`'available' \| 'unavailable' \| 'unsupp...`
Description Indicates volume control availability (`available`, `unavailable`, or `unsupported`). Type `'available' \| 'unavailable' \| 'unsupported'`
`data-hidden`	—
Description Present when volume level controls are unavailable.

Events

Event	Description
`open-change`	Fired when the popover's open state changes.