ReferenceMenus

VolumePopover

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

Import

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

Anatomy

<VolumePopover.Root>
  <VolumePopover.Trigger render={<MuteButton />} />
  <VolumePopover.Popup>
    <VolumeSlider.Root />
  </VolumePopover.Popup>
</VolumePopover.Root>

Behavior

VolumePopover 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.

Styling

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

React renders the popup as a standard <div>. Add a className to select it:

.volume-popup[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

import { Container, createPlayer, MuteButton, VolumePopover, VolumeSlider } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="react-volume-popover-basic">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <div className="react-volume-popover-basic__controls">
          <VolumePopover.Root openOnHover side="top">
            <VolumePopover.Trigger
              className="react-volume-popover-basic__trigger"
              render={
                <MuteButton render={(props, state) => <button {...props}>{state.muted ? 'Unmute' : 'Mute'}</button>} />
              }
            />
            <VolumePopover.Popup className="react-volume-popover-basic__popup">
              <VolumeSlider.Root orientation="vertical" className="react-volume-popover-basic__slider">
                <VolumeSlider.Track className="react-volume-popover-basic__track">
                  <VolumeSlider.Fill className="react-volume-popover-basic__fill" />
                </VolumeSlider.Track>
                <VolumeSlider.Thumb className="react-volume-popover-basic__thumb" />
              </VolumeSlider.Root>
            </VolumePopover.Popup>
          </VolumePopover.Root>
        </div>
      </Container>
    </Player>
  );
}

.react-volume-popover-basic {
  position: relative;
}

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

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

.react-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);
}

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

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

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

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

.react-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%);
}

API Reference

Root

Owns the popover interaction lifecycle and provides volume availability to the parts.

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`	`number`	—
Description Delay in ms before closing after pointer leaves.
`closeOnEscape`	`boolean`	—
Description Close the popup when the Escape key is pressed.
`closeOnOutsideClick`	`boolean`	—
Description Close the popup when clicking outside the trigger and popup.
`defaultOpen`	`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`	`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 accessible via the render, className, and style props.

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.

Positioned volume content. Omitted when volume level controls are unavailable.

Prop	Type	Default
`className`	`string \| function`	—
Description Class name or function returning class name from state. Type `string \| ((state: PopoverState) => string \| undefined)`
`render`	`ReactElement \| function`	—
Description Render prop for custom element. Type `ReactElement \| ((props: HTMLProps, state: PopoverState) => ReactElement \| null)`
`style`	`CSSProperties \| function`	—
Description Style or function returning style from state. Type `CSSProperties \| ((state: PopoverState) => CSSProperties \| undefined)`

Trigger

Opens the volume popup, or renders its mute-button fallback when volume level controls are unavailable.

Props

Prop	Type	Default
`className`	`string \| function`	—
Description Class name or function returning class name from state. Type `string \| ((state: PopoverState) => string \| undefined)`
`render`	`ReactElement \| function`	—
Description Render prop for custom element. Type `ReactElement \| ((props: HTMLProps, state: PopoverState) => ReactElement \| null)`
`style`	`CSSProperties \| function`	—
Description Style or function returning style from state. Type `CSSProperties \| ((state: PopoverState) => CSSProperties \| undefined)`