---
title: PlayButton
frameworkTitle:
  html: media-play-button
description: Accessible play/pause button with keyboard support and customizable rendering
---

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/play-button/react/css/BasicUsage";
import basicUsageReactTsx from "@/components/docs/demos/play-button/react/css/BasicUsage.tsx?raw";
import basicUsageReactCss from "@/components/docs/demos/play-button/react/css/BasicUsage.css?raw";

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

## Anatomy

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

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

## Behavior

PlayButton is a three-state button: **play**, **pause**, and **replay**. When media reaches the end (`ended` state), clicking restarts playback from the beginning.

## Styling

Style with the `[data-paused]` and `[data-ended]` attributes to show/hide play/pause/replay icons based on state. For example:

<FrameworkCase frameworks={["html"]}>
```css
/* Paused (but not ended) */
media-play-button[data-paused]:not([data-ended]) .play-icon { display: inline; }

/* Playing */
media-play-button:not([data-paused]) .pause-icon { display: inline; }

/* Ended */
media-play-button[data-ended] .replay-icon { display: inline; }
```
</FrameworkCase>

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

```css
/* Paused (but not ended) */
.play-button[data-paused]:not([data-ended]) .play-icon { display: inline; }

/* Playing */
.play-button:not([data-paused]) .pause-icon { display: inline; }

/* Ended */
.play-button[data-ended] .replay-icon { display: inline; }
```
</FrameworkCase>

After first play, the `data-started` attribute is added and remains present until a new source is loaded. Use this to hide the play button when media hasn't started yet:

<FrameworkCase frameworks={["html"]}>
```css
/* Hide play button before first play */
media-play-button:not([data-started]) .play-icon { display: none; }
```
</FrameworkCase>

<FrameworkCase frameworks={["react"]}>
```css
/* Hide play button before first play */
.play-button:not([data-started]) .play-icon { display: none; }
```
</FrameworkCase>

## Accessibility

Renders a `<button>` element with an automatic `aria-label` that updates based on state: "Play", "Pause", or "Replay". Override with the `label` prop, which accepts a text descriptor, literal string, or function returning either. A text descriptor contains an opaque translation key and English fallback, for example `{ key: 'buttons.play', text: 'Play video' }`. 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="PlayButton" />
