UI: Play Button Component

[mihar-22]

Implement the PlayButton component for toggling media playback. Includes core interaction logic, DOM props builder, and React/HTML implementations.

Blocked by:

• Media Store Foundation #218
• Playback Feature #239
• React Bindings #229
• ReactiveElement Bindings #230

Usage

React

import { PlayButton } from '@videojs/react';

function Controls() {
  return (
    <PlayButton onPlay={() => console.log('Playing!')}>
      ... 
    </PlayButton>
  );
}

// With render prop for custom element
<PlayButton render={(props, state) => (
    {state.paused ? 'Play' : 'Pause'}
)} />

import { usePlayButton } from '@videojs/react';

// Hook
const { props, state } = usePlayButton({
  // override any props...
});

HTML

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

API

Props

Prop	Type	Default	Description
disabled	boolean	false	Disables the button
label	string	—	Custom aria-label. Defaults to "Play", "Pause", or "Replay" based on state

Callbacks

Callback	Type	Description
onToggle	() => void	Fires on any toggle interaction
onPlayRequest	() => void	Fires before play request is made
onPauseRequest	() => void	Fires before pause request is made
onPlay	() => void	Fires when play request succeeds
onPause	() => void	Fires when pause request succeeds
onError	(error: Error) => void	Fires when play request fails (e.g., autoplay blocked)

State

Property	Type	Description
paused	boolean	Whether media is paused
ended	boolean	Whether media has ended
label	string	Computed aria-label

Data Attributes

Attribute	Values	Description
data-paused	Present/absent	Set when media is paused
data-ended	Present/absent	Set when media has ended
data-disabled	Present/absent	Set when button is disabled

Tasks

Core (@videojs/core)

• Define PlayButtonProps interface
• Define PlayButtonCallbacks interface
• Define PlayButtonState interface
• Implement PlayButtonCore class
• Implement onToggle interaction method

DOM (@videojs/dom)

• Implement getPlayButtonProps(params) function
• Define PlayButtonDataAttributes interface
• Define PlayButtonCssVars interface
• Handle keyboard interaction (Enter, Space)

React (@videojs/react)

• Implement usePlayButton(options) hook
• Implement PlayButton component
• Support render prop

HTML (@videojs/html)

• Implement PlayButtonElement element
• Declare attrs/props
• Dispatch callbacks as events

Testing

• Core unit tests
• Add conformance test suite
• Add React conformance test
• Add HTML conformance test

Design Notes

Label Computation

Label is derived from state unless explicitly provided:

function getLabel(props: Props, state: MediaState): string {
  if (props.label) return props.label;
  if (state.ended) return t('Replay');
  return state.paused ? t('Play') : t('Pause');
}

Error Handling

Play requests can fail. Surface via onError:

<PlayButton
  onError={(error) => {
    if (error.name === 'NotAllowedError') {
      showUnmutePrompt();
    }
  }}
/>

Request Flow

User clicks → onToggle → onPlayRequest/onPauseRequest → request.play/pause → onPlay/onPause/onError

Callbacks fire in order, allowing interception at each stage.