docs: add captions button (#777)

2026-08-16 02:45:09 +00:00 · 2026-03-09 14:55:44 -05:00
parent c20d884932
commit dc84216de5
10 changed files with 218 additions and 0 deletions
@@ -30,6 +30,7 @@ export {
 // UI
 export { AlertDialog, type AlertDialogContextValue, useAlertDialogContext } from './ui/alert-dialog';
 export { BufferingIndicator, type BufferingIndicatorProps } from './ui/buffering-indicator/buffering-indicator';
+export { CaptionsButton, type CaptionsButtonProps } from './ui/captions-button/captions-button';
 export { Controls } from './ui/controls';
 export type { ControlsGroupProps } from './ui/controls/controls-group';
 export type { ControlsRootProps } from './ui/controls/controls-root';
@@ -0,0 +1,10 @@
+WEBVTT
+
+00:00.000 --> 00:03.000
+This is a demo of the captions button.
+
+00:03.000 --> 00:06.000
+Captions help make video accessible to everyone.
+
+00:06.000 --> 00:09.000
+Toggle captions on and off with a single click.
@@ -0,0 +1,10 @@
+---
+import HtmlDemo from '@/components/docs/demos/HtmlDemo.astro';
+import html from './BasicUsage.html?raw';
+import './BasicUsage.css';
+---
+
+<HtmlDemo html={html} />
+<script>
+  import "./BasicUsage.ts";
+</script>
@@ -0,0 +1,34 @@
+.html-captions-button-basic {
+  position: relative;
+}
+
+.html-captions-button-basic video {
+  width: 100%;
+}
+
+.html-captions-button-basic__button {
+  padding-block: 8px;
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  background: rgba(255, 255, 255, 0.7);
+  backdrop-filter: blur(10px);
+  color: black;
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  padding-inline: 20px;
+  cursor: pointer;
+}
+
+.html-captions-button-basic__button .show-when-active {
+  display: none;
+}
+.html-captions-button-basic__button .show-when-inactive {
+  display: none;
+}
+.html-captions-button-basic__button[data-active] .show-when-active {
+  display: inline;
+}
+.html-captions-button-basic__button:not([data-active]) .show-when-inactive {
+  display: inline;
+}
@@ -0,0 +1,17 @@
+<video-player class="html-captions-button-basic">
+    <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="html-captions-button-basic__button">
+            <span class="show-when-active">Captions Off</span>
+            <span class="show-when-inactive">Captions On</span>
+        </media-captions-button>
+    </media-container>
+</video-player>
@@ -0,0 +1,2 @@
+import '@videojs/html/video/player';
+import '@videojs/html/ui/captions-button';
@@ -0,0 +1,21 @@
+.react-captions-button-basic {
+  position: relative;
+}
+
+.react-captions-button-basic video {
+  width: 100%;
+}
+
+.react-captions-button-basic__button {
+  padding-block: 8px;
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  background: rgba(255, 255, 255, 0.7);
+  backdrop-filter: blur(10px);
+  color: black;
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  padding-inline: 20px;
+  cursor: pointer;
+}
@@ -0,0 +1,30 @@
+import { CaptionsButton, createPlayer } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+import './BasicUsage.css';
+
+const Player = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player.Provider>
+      <Player.Container className="react-captions-button-basic">
+        <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="react-captions-button-basic__button"
+          render={(props, state) => (
+            <button {...props}>{state.subtitlesShowing ? 'Captions Off' : 'Captions On'}</button>
+          )}
+        />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
@@ -0,0 +1,92 @@
+---
+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"` and reflects availability via `data-availability`.
+
+When no caption or subtitle tracks are present, `data-availability="unavailable"` is set. Use this to hide the button when there are no tracks to toggle.
+
+## 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; }
+```
+
+Hide when no caption tracks are available:
+
+```css
+media-captions-button[data-availability="unavailable"] {
+  display: none;
+}
+```
+
+## 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>.
+
+## 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" />
@@ -35,6 +35,7 @@ export const sidebar: Sidebar = [
    contents: [
      // sorted alphabetically
      { slug: 'reference/buffering-indicator' },
+      { slug: 'reference/captions-button' },
      { slug: 'reference/controls' },
      { slug: 'reference/fullscreen-button' },
      { slug: 'reference/mute-button' },