ReferenceButtons

media-play-button

Accessible play/pause button with keyboard support and customizable rendering

Import

import '@videojs/html/ui/play-button';

Anatomy

<media-play-button></media-play-button>

Behavior

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

While media with autoplay is trying to start, the button shows pause, and clicking it cancels the autoplay. If the browser refuses the autoplay, the button returns to play.

Styling

Style with the [data-paused] and [data-ended] attributes to show/hide play/pause/replay icons based on state. While autoplay is pending, the button omits data-paused and adds data-started, so the pause icon shows. For example:

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

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

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

The data-started attribute is present while the media tries to autoplay, and from first play until a new source is loaded. Use this to hide the play button when media hasn’t started yet:

/* Hide play button before first play */
media-play-button:not([data-started]) .play-icon { display: none; }

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

Examples

Basic Usage

Play Pause Replay

<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline></video>
    <media-play-button class="media-play-button">
      <span class="paused">Play</span>
      <span class="playing">Pause</span>
      <span class="ended">Replay</span>
    </media-play-button>
  </media-container>
</video-player>

.video-player media-container {
  position: relative;
}

.video-player media-container video {
  width: 100%;
}

.media-play-button {
  position: absolute;
  bottom: 10px;
  left: 10px;
  padding-block: 8px;
  padding-inline: 20px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}

.media-play-button .paused {
  display: none;
}
.media-play-button .playing {
  display: none;
}
.media-play-button .ended {
  display: none;
}
.media-play-button[data-paused]:not([data-ended]) .paused {
  display: inline;
}
.media-play-button:not([data-paused]) .playing {
  display: inline;
}
.media-play-button[data-ended] .ended {
  display: inline;
}
.media-play-button[data-ended] .paused {
  display: none;
}
.media-play-button[data-ended] .playing {
  display: none;
}

import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/play-button';

API Reference

Props

Prop	Type	Default
`disabled`	`boolean`	`false`
Description Whether the button is disabled.
`label`	`object`	`''`
Description Custom label for the button. Type `{ key: string; text: string } \| string \| ((state: PlayButtonState) => Text \| string)`

State

State is reflected as data attributes for CSS styling.

Property	Type	Details
`paused`	`boolean`
Description Whether playback is paused.
`ended`	`boolean`
Description Whether playback has reached the end.
`started`	`boolean`
Description Whether playback has started (played or seeked).
`label`	`{ key: string; text: string } \| string`

Data attributes

Attribute	Description
`data-paused`	Present when the media is paused and not trying to autoplay.
`data-ended`	Present when the media has ended.
`data-started`	Present when playback has started or the media is trying to autoplay.