---
title: CastButton
frameworkTitle:
  html: media-cast-button
description: Accessible Cast toggle button with state reflection and keyboard support
---

import ComponentReference from "@/components/docs/api-reference/ComponentReference.astro";
import DocsLink from "@/components/docs/DocsLink.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/cast-button/react/css/BasicUsage";
import basicUsageReactTsx from "@/components/docs/demos/cast-button/react/css/BasicUsage.tsx?raw";
import basicUsageReactCss from "@/components/docs/demos/cast-button/react/css/BasicUsage.css?raw";

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

## Anatomy

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

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

## Behavior

Toggles a Google Cast session. Clicking the button while `disconnected` opens the Cast device picker; clicking while `connected` ends the session.

The button derives its presentation from `availability`:

- **`"unsupported"`** — the HTML custom element receives the native `hidden` attribute; the React component returns `null`.
- **`"unavailable"`** — the button remains visible and focusable with `aria-disabled="true"` and `data-disabled`, but does not open the picker. This lets a tooltip explain that no Cast device is reachable.
- **`"available"`** — the button is fully interactive unless the `disabled` prop is set.

Cast sessions come from the <DocsLink slug="concepts/cast">Google Cast</DocsLink> component. Add it to the player next to your media element; without it the button drives the browser's native Remote Playback API instead, which offers no receiver or load-request configuration.

## Styling

Style based on cast and disabled state:

<FrameworkCase frameworks={["html"]}>
```css
/* During an active session */
media-cast-button[data-cast-state="connected"] {
  color: blue;
}

/* Cast is supported, but no device is reachable */
media-cast-button[data-disabled] {
  cursor: not-allowed;
  opacity: 0.5;
}
```
</FrameworkCase>

<FrameworkCase frameworks={["react"]}>
React renders a `<button>` element. Add a `className` to style it:

```css
/* During an active session */
.cast-button[data-cast-state="connected"] {
  color: blue;
}

/* Cast is supported, but no device is reachable */
.cast-button[data-disabled] {
  cursor: not-allowed;
  opacity: 0.5;
}
```
</FrameworkCase>

Unsupported buttons are hidden automatically. No availability selector or extra hiding CSS is required.

## Accessibility

Renders a `<button>` with an automatic `aria-label`:

| Cast state | Default label |
|---|---|
| `'disconnected'` | "Start casting" |
| `'connecting'` | "Connecting" |
| `'connected'` | "Stop casting" |

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="CastButton" />
