Skip to main content
CaptionsButton toggles captions and subtitles on and off. It checks the media’s text track list for tracks with kind="captions" or kind="subtitles" and reflects availability via a data attribute.
Requires the textTrack feature to be registered with the player.

​
Import

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

​
Basic Usage

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

function PlayerControls() {
  return <CaptionsButton />;
}

​
Custom Render

import { CaptionsOnIcon, CaptionsOffIcon } from './icons';
import { CaptionsButton } from '@videojs/react';

function PlayerControls() {
  return (
    <CaptionsButton
      render={(props, state) => (
        <button {...props}>
          {state.active ? <CaptionsOnIcon /> : <CaptionsOffIcon />}
        </button>
      )}
    />
  );
}

​
Props

​
render
ReactElement | ((props: HTMLProps, state: CaptionsButton.State) => ReactElement | null)
Custom render prop. Receives the computed HTML props and current state.
​
label
string | ((state: CaptionsButton.State) => string)
Override the automatic aria-label. By default: "Enable captions" or "Disable captions".
​
disabled
boolean
Disables the button.
​
className
string | ((state: CaptionsButton.State) => string)
CSS class name or a function that receives state and returns a class name.
​
style
CSSProperties | ((state: CaptionsButton.State) => CSSProperties)
Inline style or a function that receives state and returns a style object.

​
State Data Attributes

AttributeValue / Description
data-activePresent when captions/subtitles are currently enabled.
data-availability"available" | "unavailable" — whether any caption or subtitle tracks exist.

​
CSS Styling Example

/* Hide when no caption tracks are available */
.captions-button[data-availability="unavailable"] {
  display: none;
}

/* Active state */
.captions-button[data-active] {
  color: yellow;
}

​
Accessibility

Renders a <button> element. The aria-label updates automatically: "Enable captions" or "Disable captions". Keyboard activation: Enter / Space.

Build docs developers (and LLMs) love

Get started for freeTalk to us