media-captions-button

Accessible captions toggle button with availability detection and state reflection

Anatomy

<media-captions-button></media-captions-button>

Behavior

Toggles captions and subtitles on and off. The button checks the media’s text track list for tracks with kind="captions" or kind="subtitles". When none are present, the HTML custom element receives the native hidden attribute and the React component returns null. The raw state remains available as data-availability.

An explicitly disabled button with caption tracks stays visible and focusable with aria-disabled="true" and data-disabled, but does not toggle captions.

When menuTrigger is enabled and multiple caption or subtitle tracks are available, activation opens the linked captions menu instead of toggling captions directly. React enables menuTrigger automatically when a CaptionsButton is rendered inside Menu.Trigger.

Styling

Style the button based on active state:

media-captions-button[data-active] .icon-on { display: inline; }
media-captions-button:not([data-active]) .icon-off { display: inline; }

Style an explicitly disabled, available button:

media-captions-button[data-disabled] {
  cursor: not-allowed;
  opacity: 0.5;
}

The button hides automatically when no caption tracks are available. No availability selector or extra hiding CSS is required.

Accessibility

Renders a <button> with an automatic aria-label: “Disable captions” when active, “Enable captions” when inactive. Override with the label prop. Keyboard activation: Enter / Space.

In menu-trigger mode, the button behaves as a menu trigger and reflects menu state through the trigger attributes.

Examples

Basic Usage

import { CaptionsButton, createPlayer } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

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

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" />
        </Video>
        <CaptionsButton
          className="media-captions-button"
          render={(props, state) => (
            <button {...props}>{state.subtitlesShowing ? 'Captions Off' : 'Captions On'}</button>
          )}
        />
      </Player.Container>
    </Player.Provider>
  );
}

.media-container {
  position: relative;
}

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

.media-captions-button {
  position: absolute;
  bottom: 10px;
  left: 10px;
  padding-block: 8px;
  padding-inline: 20px;
  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);
}

Captions Off Captions On

<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" />
        </video>
        <media-captions-button class="media-captions-button">
            <span class="active">Captions Off</span>
            <span class="inactive">Captions On</span>
        </media-captions-button>
    </media-container>
</video-player>

.video-player {
  position: relative;
}

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

.media-captions-button {
  position: absolute;
  bottom: 10px;
  left: 10px;
  padding-block: 8px;
  padding-inline: 20px;
  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-captions-button .active {
  display: none;
}
.media-captions-button .inactive {
  display: none;
}
.media-captions-button[data-active] .active {
  display: inline;
}
.media-captions-button:not([data-active]) .inactive {
  display: inline;
}

import '@videojs/html/video/player';
import '@videojs/html/ui/captions-button';

API Reference

Props

Prop	Type	Default
`disabled`	`boolean`	`false`
Attribute `disabled` Description Whether the button is disabled.
`label`	`Text \| string \| Text) \| function`	`''`
Attribute `label` Description Custom label for the button. Type `Text \| string \| ((state: CaptionsButtonState) => string \| Text)`
`menuTrigger`	`boolean`	`false`
Attribute `menu-trigger` Description When true with multiple tracks, pointer activation opens a menu instead of toggling. React sets this automatically inside `Menu.Trigger`.

State

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

State is reflected as data attributes for CSS styling.

Property	Type	Details
`availability`	`'available' \| 'unavailable'`
Description Whether caption/subtitle tracks are present.
`disabled`	`boolean`
Description Non-interactive but still focusable (mirrors `aria-disabled`).
`hidden`	`boolean`
Description Whether the button is hidden because no caption tracks are present.
`subtitlesShowing`	`boolean`
Description Whether captions/subtitles are currently enabled.
`label`	`Text \| string`

Data attributes

Attribute	Type	Details
`data-active`
Description Present when captions are enabled.
`data-availability`	`'available' \| 'unavailable'`
Description Indicates captions availability (`available` or `unavailable`).
`data-disabled`
Description Present when the button is non-interactive (mirrors `aria-disabled`).
`data-hidden`
Description Present when the button is hidden because no caption tracks are present.