media-captions-radio-group

A menu radio group for selecting caption and subtitle tracks

Creates radio items from the player text track state and selects the showing caption or subtitle track.

Anatomy

<media-captions-radio-group>
  <template>
    <media-menu-radio-item>
      <span data-part="label"></span>
      <media-menu-item-indicator></media-menu-item-indicator>
    </media-menu-radio-item>
  </template>
</media-captions-radio-group>

Behavior

The group is available when the configured media exposes at least one caption or subtitle track. The first generated option is Off; selecting it hides captions. Track labels use the track label, then language, then kind. Pass formatTrack to customize the visible labels.

<media-captions-radio-group> generates <media-menu-radio-item> children, including the Off item. Add an optional <template> with a single <media-menu-radio-item> to customize each generated item.

Styling

Attribute	Values	Description
`data-active`	Present / absent	Present when captions are enabled.
`data-disabled`	Present / absent	Present when track selection is disabled.
`data-hidden`	Present / absent	Present when caption or subtitle tracks are unavailable.
`data-availability`	`"available"` / `"unavailable"`	Whether caption or subtitle tracks are available.

Unavailable groups receive the native hidden attribute.

Accessibility

The group uses the menu radio group pattern.

The element receives an accessible label from the label property or defaults to Captions.

Examples

Basic usage

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

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

function CaptionsMenu(): ReactNode {
  return (
    <Menu.Root side="top" align="end">
      <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
        Captions
      </Menu.Trigger>
      <Menu.Content className="menu">
        <CaptionsRadioGroup
          className="menu-group"
          renderItem={(props, item) => (
            <Menu.RadioItem {...props} className="menu-item">
              {item.label}
              <Menu.ItemIndicator checked={item.checked} forceMount className="menu-indicator">
                ✓
              </Menu.ItemIndicator>
            </Menu.RadioItem>
          )}
        />
      </Menu.Content>
    </Menu.Root>
  );
}

export default function BasicUsage() {
  return (
    <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">
          <CaptionsMenu />
        </div>
      </Container>
    </Player>
  );
}

.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;
  box-sizing: border-box;
  display: grid;
  gap: 2px;
  min-width: 180px;
  max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
  max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
  padding: 6px;
  margin: 0;
  overflow: auto;
  overscroll-behavior: none;
  font-size: 14px;
  color: white;
  background: rgba(0, 0, 0, 0.88);
  border: 0;
  border-radius: 8px;
  backdrop-filter: blur(10px);
}

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

.menu-item {
  display: flex;
  gap: 8px;
  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] {
  background: rgba(255, 255, 255, 0.16);
}

.menu-indicator {
  opacity: 0;
}

[role="menuitemradio"][aria-checked="true"] .menu-indicator {
  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="captions-menu" class="settings-trigger">Captions</button>
            <media-menu id="captions-menu" side="top" align="end" class="menu">
                <media-captions-radio-group class="menu-group" label="Captions">
                    <template>
                        <media-menu-radio-item class="menu-item">
                            <span data-part="label"></span>
                            <media-menu-item-indicator force-mount class="menu-indicator">✓</media-menu-item-indicator>
                        </media-menu-radio-item>
                    </template>
                </media-captions-radio-group>
            </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;
  box-sizing: border-box;
  display: grid;
  gap: 2px;
  min-width: 180px;
  max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
  max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
  padding: 6px;
  overflow: auto;
  overscroll-behavior: none;
  font-size: 14px;
  color: white;
  background: rgba(0, 0, 0, 0.88);
  border-radius: 8px;
  backdrop-filter: blur(10px);
}

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

.menu-item {
  display: flex;
  gap: 8px;
  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] {
  background: rgba(255, 255, 255, 0.16);
}

.menu-indicator {
  opacity: 0;
}

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

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

API Reference

Props

Prop	Type	Default
`disabled`	`boolean`	`false`
Attribute `disabled` Description Whether track selection is disabled.
`formatTrack`	`Text) \| function`	`formatTrackLabel`
Attribute `format-track` Description Custom formatter for visible track labels. Type `((track: MediaTextTrack) => string \| Text)`
`label`	`Text \| string \| Text) \| function`	`''`
Attribute `label` Description Custom label for the options group. Type `Text \| string \| ((state: CaptionsRadioGroupState) => string \| Text)`

State

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

State is reflected as data attributes for CSS styling.

Property	Type	Details
`subtitlesShowing`	`boolean`
Description Whether captions/subtitles are currently enabled.
`value`	`string`
Description Current radio-group value.
`options`	`CaptionsRadioGroupOption[]`
Description Ordered options displayed by platform adapters.
`disabled`	`boolean`
Description Whether the entire option group is disabled.
`hidden`	`boolean`
Description Whether the option group is hidden because no meaningful selection is available.
`availability`	`'available' \| 'unavailable'`
Description Whether the media exposes a meaningful selection.
`label`	`Text \| string`

Data attributes

Attribute	Type	Details
`data-active`
Description Present when captions are enabled.
`data-disabled`
Description Present when track selection is disabled.
`data-hidden`
Description Present when track selection is unavailable.
`data-availability`	`'available' \| 'unavailable'`
Description Indicates captions availability (`available` or `unavailable`).