media-menu

A composable menu component for settings, option selection, and actions

Anatomy

<Menu.Root>
  <Menu.Trigger>Settings</Menu.Trigger>
  <Menu.Content>
    <Menu.View>
      <Menu.Root>
        <Menu.Trigger type="playback-rate">
          Speed <Menu.ItemValue />
        </Menu.Trigger>
        <Menu.Content>
          <Menu.Back />
          <Menu.RadioGroup value={rate} onValueChange={setRate}>
            <Menu.GroupLabel>Speed</Menu.GroupLabel>
            <Menu.RadioItem value="1">Normal</Menu.RadioItem>
            <Menu.RadioItem value="1.5">1.5x</Menu.RadioItem>
          </Menu.RadioGroup>
        </Menu.Content>
      </Menu.Root>

      <Menu.Root>
        <Menu.Trigger type="captions">
          Captions <Menu.ItemValue />
        </Menu.Trigger>
        <Menu.Content>
          <Menu.Back />
          <Menu.RadioGroup value={captions} onValueChange={setCaptions}>
            <Menu.GroupLabel>Captions</Menu.GroupLabel>
            <Menu.RadioItem value="off">Off</Menu.RadioItem>
            <Menu.RadioItem value="en">English</Menu.RadioItem>
          </Menu.RadioGroup>
        </Menu.Content>
      </Menu.Root>

      <Menu.Item onSelect={copyLink}>Copy link</Menu.Item>
    </Menu.View>
  </Menu.Content>
</Menu.Root>

<button type="button" commandfor="settings-menu">Settings</button>

<media-menu id="settings-menu">
  <media-menu-view>
    <media-menu-item commandfor="speed-menu" type="playback-rate">
      Speed <media-menu-item-value></media-menu-item-value>
    </media-menu-item>
    <media-menu-item commandfor="captions-menu" type="captions">
      Captions <media-menu-item-value></media-menu-item-value>
    </media-menu-item>
    <media-menu-item>Copy link</media-menu-item>
  </media-menu-view>

  <media-menu id="speed-menu">
    <media-menu-back></media-menu-back>
    <media-menu-radio-group value="1">
      <media-menu-group-label>Speed</media-menu-group-label>
      <media-menu-radio-item value="1">Normal</media-menu-radio-item>
      <media-menu-radio-item value="1.5">1.5x</media-menu-radio-item>
    </media-menu-radio-group>
  </media-menu>

  <media-menu id="captions-menu">
    <media-menu-back></media-menu-back>
    <media-menu-radio-group value="off">
      <media-menu-group-label>Captions</media-menu-group-label>
      <media-menu-radio-item value="off">Off</media-menu-radio-item>
      <media-menu-radio-item value="en">English</media-menu-radio-item>
    </media-menu-radio-group>
  </media-menu>
</media-menu>

Behavior

Menus open from a trigger and close when you select an item, click outside, move focus away, or press Escape. Root menus are positioned against their trigger with side and align.

Nest Menu.Root inside Menu.Content to create an in-place submenu. In HTML, link a submenu with commandfor. Wrap the root list in Menu.View or <media-menu-view> when the root list and child menus share one animated viewport.

Set type="playback-rate" or type="captions" on a submenu trigger when it represents a media setting. Menu.ItemValue and <media-menu-item-value> read that setting context and display the current value, such as 1.5x, English, or Off.

Styling

Use data attributes to style open state, highlighted items, selected radio items, and submenu views:

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

media-menu-item[data-highlighted] {
  background: rgba(255, 255, 255, 0.16);
}

media-menu-radio-item[aria-checked="true"] {
  font-weight: 600;
}

Accessibility

Menu content renders with role="menu". Items use menuitem, menuitemradio, or menuitemcheckbox roles. Radio and checkbox items reflect selection with aria-checked.

Keyboard controls:

Enter / Space: Select the highlighted item.
Arrow Up / Arrow Down: Move between items.
Arrow Right: Open a submenu.
Arrow Left: Return to the parent menu.
Escape: Close the root menu or return from a submenu.

Use Menu.GroupLabel or <media-menu-group-label> inside grouped choices so the group receives an accessible label.

Examples

Basic usage

import { createPlayer, Menu, useCaptionsOptions, usePlaybackRateOptions } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';
import type { ReactNode } from 'react';

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

function SettingsMenu(): ReactNode {
  const playbackRate = usePlaybackRateOptions();
  const captions = useCaptionsOptions();
  const hasPlaybackRate = playbackRate?.state.availability === 'available';
  const hasCaptions = captions?.state.availability === 'available';

  if (!hasPlaybackRate && !hasCaptions) return null;

  return (
    <Menu.Root side="top" align="end">
      <Menu.Trigger className="settings-trigger" aria-label="Settings" render={<button type="button" />}>
        Settings
      </Menu.Trigger>
      <Menu.Content className="menu">
        <Menu.View className="menu-panel">
          {hasPlaybackRate && playbackRate ? (
            <Menu.Root>
              <Menu.Trigger
                type="playback-rate"
                className="menu-item"
                render={(props) => (
                  <div {...props}>
                    <span>Speed</span>
                    <span className="menu-value">
                      <Menu.ItemValue />
                      <span aria-hidden="true">›</span>
                    </span>
                  </div>
                )}
              />
              <Menu.Content className="menu-panel">
                <Menu.Back className="menu-back">Speed</Menu.Back>
                <Menu.RadioGroup
                  className="menu-group"
                  value={playbackRate.value}
                  onValueChange={playbackRate.setValue}
                  aria-label="Playback rate"
                >
                  {playbackRate.options.map((option) => (
                    <Menu.RadioItem
                      key={option.value}
                      value={option.value}
                      disabled={option.disabled}
                      className="menu-item"
                    >
                      <span>{option.label}</span>
                      <Menu.ItemIndicator checked={option.value === playbackRate.value} forceMount>
                        ✓
                      </Menu.ItemIndicator>
                    </Menu.RadioItem>
                  ))}
                </Menu.RadioGroup>
              </Menu.Content>
            </Menu.Root>
          ) : null}

          {hasCaptions && captions ? (
            <Menu.Root>
              <Menu.Trigger
                type="captions"
                className="menu-item"
                render={(props) => (
                  <div {...props}>
                    <span>Captions</span>
                    <span className="menu-value">
                      <Menu.ItemValue />
                      <span aria-hidden="true">›</span>
                    </span>
                  </div>
                )}
              />
              <Menu.Content className="menu-panel">
                <Menu.Back className="menu-back">Captions</Menu.Back>
                <Menu.RadioGroup
                  className="menu-group"
                  value={captions.value}
                  onValueChange={captions.setValue}
                  aria-label="Captions"
                >
                  {captions.options.map((option) => (
                    <Menu.RadioItem
                      key={option.value}
                      value={option.value}
                      disabled={option.disabled}
                      className="menu-item"
                    >
                      <span>{option.label}</span>
                      <Menu.ItemIndicator checked={option.value === captions.value} forceMount>
                        ✓
                      </Menu.ItemIndicator>
                    </Menu.RadioItem>
                  ))}
                </Menu.RadioGroup>
              </Menu.Content>
            </Menu.Root>
          ) : null}

          <Menu.Item className="menu-item" onSelect={() => navigator.clipboard?.writeText(window.location.href)}>
            Copy link
          </Menu.Item>
        </Menu.View>
      </Menu.Content>
    </Menu.Root>
  );
}

export default function BasicUsage() {
  return (
    <Player.Provider>
      <Player.Container className="media-container">
        <Video
          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
          autoPlay
          muted
          playsInline
          loop
        >
          <track kind="captions" src="/docs/demos/captions-button/captions.vtt" srcLang="en" label="English" />
          <track kind="subtitles" src="/docs/demos/captions-button/captions.vtt" srcLang="es" label="Spanish" />
        </Video>
        <div className="menu-bar">
          <SettingsMenu />
        </div>
      </Player.Container>
    </Player.Provider>
  );
}

.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.menu-bar {
  position: absolute;
  right: 10px;
  bottom: 10px;
}

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

.menu {
  --media-menu-side-offset: 8px;
  --menu-transition-duration: 220ms;
  position: relative;
  box-sizing: border-box;
  width: var(--media-menu-width);
  min-width: 180px;
  max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
  height: var(--media-menu-height);
  max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
  padding: 6px;
  margin: 0;
  overflow: hidden;
  overscroll-behavior: none;
  font-size: 14px;
  color: white;
  background: rgba(0, 0, 0, 0.88);
  border: 0;
  border-radius: 8px;
  backdrop-filter: blur(10px);
  transition-timing-function: ease-in-out;
  transition-duration: var(--menu-transition-duration);
  transition-property: width, height, opacity, filter;
}

.menu-panel {
  position: absolute;
  inset: 0;
  display: grid;
  gap: 2px;
  padding: 6px;
  overflow: auto;
  overscroll-behavior: none;
  outline: none;
  translate: 0 0;
  transition-timing-function: ease-in-out;
  transition-duration: var(--menu-transition-duration);
  transition-property: translate, filter;
  will-change: translate;
}

.menu-panel[data-starting-style],
.menu-panel[data-ending-style] {
  overflow: hidden;
}

.menu-panel[data-menu-root-view][data-menu-view-state="inactive"] {
  filter: blur(8px);
  translate: -100% 0;
}

.menu-panel[data-submenu] {
  z-index: 1;
}

.menu-panel[data-submenu]:not([data-open], [data-ending-style]) {
  translate: -100% 0;
  transition-property: none;
}

.menu-panel[data-submenu][data-starting-style],
.menu-panel[data-submenu][data-ending-style] {
  pointer-events: none;
  filter: blur(8px);
}

.menu-panel[data-submenu][data-starting-style][data-direction="forward"],
.menu-panel[data-submenu][data-ending-style][data-direction="back"] {
  translate: 100% 0;
}

.menu-panel[data-submenu][data-ending-style][data-direction="forward"],
.menu-panel[data-submenu][data-starting-style][data-direction="back"] {
  translate: -100% 0;
}

.menu-item,
.menu-back {
  display: flex;
  align-items: center;
  justify-content: space-between;
  min-height: 32px;
  padding: 0 10px;
  font: inherit;
  color: inherit;
  cursor: pointer;
  background: none;
  border: 0;
  border-radius: 6px;
}

.menu-item[data-highlighted],
.menu-back:hover {
  background: rgba(255, 255, 255, 0.16);
}

.menu-value {
  display: inline-flex;
  gap: 8px;
  align-items: center;
  color: rgba(255, 255, 255, 0.72);
}

.menu-group {
  display: grid;
  gap: 2px;
}

[role="menuitemradio"] [aria-hidden],
.menu-item [aria-hidden] {
  font-size: 18px;
  line-height: 1;
  color: rgba(255, 255, 255, 0.72);
}

[role="menuitemradio"] span:last-child {
  opacity: 0;
}

[role="menuitemradio"][aria-checked="true"] span:last-child {
  opacity: 1;
}

<video-player class="video-player">
    <media-container>
        <video
            src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
            autoplay
            muted
            playsinline
            loop
        >
            <track kind="captions" src="/docs/demos/captions-button/captions.vtt" srclang="en" label="English" />
            <track kind="subtitles" src="/docs/demos/captions-button/captions.vtt" srclang="es" label="Spanish" />
        </video>
        <div class="menu-bar">
            <button type="button" commandfor="settings-menu" class="settings-trigger">Settings</button>
            <media-menu id="settings-menu" side="top" align="end" class="menu">
                <media-menu-view class="menu-panel">
                    <media-menu-item commandfor="speed-menu" type="playback-rate" class="menu-item">
                        <span>Speed</span>
                        <span class="menu-value">
                            <media-menu-item-value></media-menu-item-value>
                            <span aria-hidden="true">›</span>
                        </span>
                    </media-menu-item>
                    <media-menu-item commandfor="captions-menu" type="captions" class="menu-item">
                        <span>Captions</span>
                        <span class="menu-value">
                            <media-menu-item-value></media-menu-item-value>
                            <span aria-hidden="true">›</span>
                        </span>
                    </media-menu-item>
                    <media-menu-item class="menu-item">Copy link</media-menu-item>
                </media-menu-view>

                <media-menu id="speed-menu" class="menu-panel">
                    <media-menu-back class="menu-back">Speed</media-menu-back>
                    <media-playback-rate-radio-group class="menu-group">
                        <template>
                            <media-menu-radio-item class="menu-item">
                                <span data-part="label"></span>
                                <media-menu-item-indicator force-mount>✓</media-menu-item-indicator>
                            </media-menu-radio-item>
                        </template>
                    </media-playback-rate-radio-group>
                </media-menu>

                <media-menu id="captions-menu" class="menu-panel">
                    <media-menu-back class="menu-back">Captions</media-menu-back>
                    <media-captions-radio-group class="menu-group">
                        <template>
                            <media-menu-radio-item class="menu-item">
                                <span data-part="label"></span>
                                <media-menu-item-indicator force-mount>✓</media-menu-item-indicator>
                            </media-menu-radio-item>
                        </template>
                    </media-captions-radio-group>
                </media-menu>
            </media-menu>
        </div>
    </media-container>
</video-player>

.video-player,
.video-player media-container {
  position: relative;
  display: block;
}

.video-player video {
  width: 100%;
}

.menu-bar {
  position: absolute;
  right: 10px;
  bottom: 10px;
}

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

.menu {
  --media-menu-side-offset: 8px;
  --menu-transition-duration: 220ms;
  position: relative;
  box-sizing: border-box;
  width: var(--media-menu-width);
  min-width: 180px;
  max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
  height: var(--media-menu-height);
  max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
  padding: 6px;
  overflow: hidden;
  overscroll-behavior: none;
  font-size: 14px;
  color: white;
  background: rgba(0, 0, 0, 0.88);
  border-radius: 8px;
  backdrop-filter: blur(10px);
  transition-timing-function: ease-in-out;
  transition-duration: var(--menu-transition-duration);
  transition-property: width, height, opacity, filter;
}

.menu-panel {
  position: absolute;
  inset: 0;
  display: grid;
  gap: 2px;
  padding: 6px;
  overflow: auto;
  overscroll-behavior: none;
  outline: none;
  translate: 0 0;
  transition-timing-function: ease-in-out;
  transition-duration: var(--menu-transition-duration);
  transition-property: translate, filter;
  will-change: translate;
}

.menu-panel[data-starting-style],
.menu-panel[data-ending-style] {
  overflow: hidden;
}

.menu-panel[data-menu-root-view][data-menu-view-state="inactive"] {
  filter: blur(8px);
  translate: -100% 0;
}

.menu-panel[data-submenu] {
  z-index: 1;
}

.menu-panel[data-submenu]:not([data-open], [data-ending-style]) {
  translate: -100% 0;
  transition-property: none;
}

.menu-panel[data-submenu][data-starting-style],
.menu-panel[data-submenu][data-ending-style] {
  pointer-events: none;
  filter: blur(8px);
}

.menu-panel[data-submenu][data-starting-style][data-direction="forward"],
.menu-panel[data-submenu][data-ending-style][data-direction="back"] {
  translate: 100% 0;
}

.menu-panel[data-submenu][data-ending-style][data-direction="forward"],
.menu-panel[data-submenu][data-starting-style][data-direction="back"] {
  translate: -100% 0;
}

.menu-item,
.menu-back {
  display: flex;
  align-items: center;
  justify-content: space-between;
  min-height: 32px;
  padding: 0 10px;
  font: inherit;
  color: inherit;
  cursor: pointer;
  background: none;
  border: 0;
  border-radius: 6px;
}

.menu-item[data-highlighted],
.menu-back:hover {
  background: rgba(255, 255, 255, 0.16);
}

.menu-value {
  display: inline-flex;
  gap: 8px;
  align-items: center;
  color: rgba(255, 255, 255, 0.72);
}

.menu-value [aria-hidden] {
  font-size: 18px;
  line-height: 1;
}

.menu-group {
  display: grid;
  gap: 2px;
}

media-menu-item-indicator {
  opacity: 0;
}

media-menu-radio-item[aria-checked="true"] media-menu-item-indicator {
  opacity: 1;
}

import '@videojs/html/video/player';
import '@videojs/html/ui/menu';
import '@videojs/html/ui/playback-rate-radio-group';
import '@videojs/html/ui/captions-radio-group';

API Reference

media-menu

Props

Prop	Type	Default
`align`	`'start' \| 'center' \| 'end'`	`'start'`
Attribute `align` Description Alignment along the trigger's edge. Root menus only.
`closeOnEscape`	`boolean`	`true`
Attribute `close-on-escape` Description Close the menu when Escape is pressed at root level.
`closeOnOutsideClick`	`boolean`	`true`
Attribute `close-on-outside-click` Description Close the menu when clicking outside. Root menus only.
`defaultOpen`	`boolean`	`false`
Attribute `default-open` Description Initial open state (uncontrolled).
`isSubmenu`	`boolean`	`false`
Attribute `is-submenu` Description True when this menu instance is nested inside a parent menu's content.
`open`	`boolean`	`false`
Attribute `open` Description Controlled open state.
`side`	`'top' \| 'bottom' \| 'left' \| 'right'`	`'bottom'`
Attribute `side` Description Which side of the trigger the menu appears on. Root menus only.

State

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

State is reflected as data attributes for CSS styling.

Property	Type	Details
`open`	`boolean`
`status`	`'idle' \| 'starting' \| 'ending'`
`side`	`'top' \| 'bottom' \| 'left' \| 'right' \|...`
Type `'top' \| 'bottom' \| 'left' \| 'right' \| undefined`
`align`	`'start' \| 'center' \| 'end' \| undefined`
`isSubmenu`	`boolean`
Description Whether this menu is nested inside another menu's content.
`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 menu is open.
`data-side`	`undefined \| 'top' \| 'bottom' \| 'left'...`
Description Popover positioning side. Absent on submenus. Type `undefined \| 'top' \| 'bottom' \| 'left' \| 'right'`
`data-align`	`undefined \| 'start' \| 'center' \| 'end'`
Description Popover positioning alignment. Absent on submenus.
`data-submenu`
Description Present on Content when this menu is nested inside a parent menu.

CSS custom properties

Variable	Details
`--media-menu-width`
Description Width of the incoming submenu view (px). Set on root Content before each transition.
`--media-menu-height`
Description Height of the incoming submenu view (px). Set on root Content before each transition.
`--media-menu-available-width`
Description Viewport-constrained max width for the menu (px). Set from popover positioning.
`--media-menu-available-height`
Description Viewport-constrained max height for the menu (px). Set from popover positioning.

media-menu-back

Button that navigates back to the parent menu view. Place at the top of a submenu Content.

Props

Prop	Type	Default	Details
`label`	`string`	`—`
Attribute `label` Description Accessible label for the back button.

media-menu-checkbox-item

A checkbox-style menu item. Renders a <div> with role="menuitemcheckbox".

Props

Prop	Type	Default
`checked`	`boolean`	`—`
Attribute `checked` Description Whether the item is currently checked.
`disabled`	`boolean`	`—`
Attribute `disabled` Description Whether the item is disabled.
`onCheckedChange`	`(checked: boolean) => void`	`—`
Attribute `on-checked-change` Description Called when the checked state should change.

Content

Container for menu items. Positioned relative to the trigger at root level; renders in-place as a submenu panel when nested.

Data attributes

Attribute	Type	Details
`data-open`
Description Present when the menu is open.
`data-side`	`undefined \| 'top' \| 'bottom' \| 'left'...`
Description Popover positioning side. Absent on submenus. Type `undefined \| 'top' \| 'bottom' \| 'left' \| 'right'`
`data-align`	`undefined \| 'start' \| 'center' \| 'end'`
Description Popover positioning alignment. Absent on submenus.
`data-submenu`
Description Present on Content when this menu is nested inside a parent menu.

media-menu-group

Groups related menu items. Renders a <div> with role="group".

media-menu-group-label

Non-interactive label for a group of items. Renders a <div>.

media-menu-item

A single action in the menu. Renders a <div> with role="menuitem".

Props

Prop	Type	Default
`disabled`	`boolean`	`—`
Attribute `disabled` Description Whether the item is disabled.
`onSelect`	`() => void`	`—`
Attribute `on-select` Description Called when the item is selected.
`type`	`MenuItemSettingType`	`—`
Attribute `type` Description Setting kind for submenu triggers (`playback-rate` or `captions`).

media-menu-item-indicator

Visual indicator for a checked state. Only renders when checked is true (or forceMount is set).

Props

Prop	Type	Default
`checked`	`boolean`	`—`
Attribute `checked` Description Whether the indicator is currently shown. Typically bound to the parent item's checked state.
`forceMount`	`boolean`	`—`
Attribute `force-mount` Description When `true`, renders even when unchecked (useful for animating out). Defaults to `false`.

media-menu-item-value

Displays the current value for a settings menu item from Menu.Item or Menu.Trigger context.

Data attributes

Attribute	Type	Details
`data-open`
Description Present when the menu is open.
`data-side`	`undefined \| 'top' \| 'bottom' \| 'left'...`
Description Popover positioning side. Absent on submenus. Type `undefined \| 'top' \| 'bottom' \| 'left' \| 'right'`
`data-align`	`undefined \| 'start' \| 'center' \| 'end'`
Description Popover positioning alignment. Absent on submenus.
`data-submenu`
Description Present on Content when this menu is nested inside a parent menu.

media-menu-radio-group

A group of mutually exclusive radio items. Renders a <div> with role="group".

Props

Prop	Type	Default
`onValueChange`	`(value: string) => void`	`—`
Attribute `on-value-change` Description Called when the user selects a radio item.
`value`	`string`	`—`
Attribute `value` Description The currently selected value.

media-menu-radio-item

A radio-style menu item. Renders a <div> with role="menuitemradio".

Props

Prop	Type	Default
`disabled`	`boolean`	`—`
Attribute `disabled` Description Whether the item is disabled.
`value`	`string`	`—`
Attribute `value` Description The value this item represents.

media-menu-separator

Visual divider between groups of items. Renders a <div> with role="separator".

Trigger

Button that toggles the menu visibility. At root level renders a <button>. When inside a parent menu (as a submenu trigger), renders as a <div role="menuitem"> that pushes the submenu on click or ArrowRight.

Props

Prop	Type	Default
`disabled`	`boolean`	`—`
Attribute `disabled` Description Disables the trigger.
`type`	`MenuItemSettingType`	`—`
Attribute `type` Description Setting kind for submenu triggers (`playback-rate` or `captions`).

media-menu-view

Root menu view inside the menu viewport.

Anatomy

Behavior

Styling

Accessibility

Examples

Basic usage

API Reference

Root media-menu

Props

State

Data attributes

CSS custom properties

Back media-menu-back

Props

CheckboxItem media-menu-checkbox-item

Props

Content Content

Data attributes

Group media-menu-group

GroupLabel media-menu-group-label

Item media-menu-item

Props

ItemIndicator media-menu-item-indicator

Props

ItemValue media-menu-item-value

Data attributes

RadioGroup media-menu-radio-group

Props

RadioItem media-menu-radio-item

Props

Separator media-menu-separator

Trigger Trigger

Props

View media-menu-view

media-menu

media-menu-back

media-menu-checkbox-item

Content

media-menu-group

media-menu-group-label

media-menu-item

media-menu-item-indicator

media-menu-item-value

media-menu-radio-group

media-menu-radio-item

media-menu-separator

Trigger

media-menu-view