---
title: CaptionsButton
frameworkTitle:
  html: media-captions-button
description: Accessible captions toggle button with availability detection and state reflection
---

import ComponentReference from "@/components/docs/api-reference/ComponentReference.astro";
import FrameworkCase from "@/components/docs/FrameworkCase.astro";
import StyleCase from "@/components/docs/StyleCase.astro";
import Demo from "@/components/docs/demos/Demo.astro";

{/* React demos */}
import BasicUsageDemoReact from "@/components/docs/demos/captions-button/react/css/BasicUsage";
import basicUsageReactTsx from "@/components/docs/demos/captions-button/react/css/BasicUsage.tsx?raw";
import basicUsageReactCss from "@/components/docs/demos/captions-button/react/css/BasicUsage.css?raw";

{/* HTML demos */}
import BasicUsageDemoHtml from "@/components/docs/demos/captions-button/html/css/BasicUsage.astro";
import basicUsageHtml from "@/components/docs/demos/captions-button/html/css/BasicUsage.html?raw";
import basicUsageHtmlCss from "@/components/docs/demos/captions-button/html/css/BasicUsage.css?raw";
import basicUsageHtmlTs from "@/components/docs/demos/captions-button/html/css/BasicUsage.ts?raw";

## Anatomy

<FrameworkCase frameworks={["react"]}>
```tsx
<CaptionsButton />
```
</FrameworkCase>

<FrameworkCase frameworks={["html"]}>
```html
<media-captions-button></media-captions-button>
```
</FrameworkCase>

## 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:

```css
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:

```css
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: <kbd>Enter</kbd> / <kbd>Space</kbd>.

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

## Examples

### Basic Usage

<FrameworkCase frameworks={["react"]}>
  <StyleCase styles={["css"]}>
    <Demo files={[
      { title: "App.tsx", code: basicUsageReactTsx, lang: "tsx" },
      { title: "App.css", code: basicUsageReactCss, lang: "css" },
    ]}>
      <BasicUsageDemoReact client:idle />
    </Demo>
  </StyleCase>
</FrameworkCase>

<FrameworkCase frameworks={["html"]}>
  <StyleCase styles={["css"]}>
    <Demo files={[
      { title: "index.html", code: basicUsageHtml, lang: "html" },
      { title: "index.css", code: basicUsageHtmlCss, lang: "css" },
      { title: "index.ts", code: basicUsageHtmlTs, lang: "ts" },
    ]}>
      <BasicUsageDemoHtml />
    </Demo>
  </StyleCase>
</FrameworkCase>

<ComponentReference component="CaptionsButton" />
