Skip to main content
UI components are controls like buttons, sliders, and time displays. Every UI component renders exactly one HTML element, giving you full control over styling and behavior while handling complex interactions for you.

​
Where to put components

UI components can go anywhere inside a <Player.Provider>.However, place your components inside <Player.Container> so they go fullscreen with the player, respond to user activity, and more.
<Player.Provider>
  <Player.Container>
    <Video src="video.mp4" />
    <PlayButton />
    <TimeSlider.Root>
      <TimeSlider.Track>
        <TimeSlider.Fill />
      </TimeSlider.Track>
      <TimeSlider.Thumb />
    </TimeSlider.Root>
  </Player.Container>
</Player.Provider>

​
Styling and customization

​
Data attributes

Components reflect player state as data-* attributes on their element. For example, data-paused or data-volume-level="high". This lets you style state changes in pure CSS: 
/* Show/hide icons based on play state */
.play-icon  { display: none; }
.pause-icon { display: none; }

button[data-paused] .play-icon        { display: inline; }
button:not([data-paused]) .pause-icon { display: inline; }
Some components also expose CSS custom properties for continuous values like fill percentage and pointer position. Sliders set --media-slider-fill and --media-slider-pointer. See individual component reference pages for specifics.

​
The render prop (React)

The render prop is the primary customization mechanism in React. It accepts a function that receives props and state, and returns your element. Always spread {...props} to keep event handlers, ARIA attributes, and data attributes working: 
<PlayButton
  render={(props, state) => (
    <button {...props}>
      {state.paused ? 'Play' : 'Pause'}
    </button>
  )}
/>
className and style also accept functions of state for dynamic styling without a full render prop: 
<PlayButton
  className={(state) =>
    state.paused ? 'btn btn--paused' : 'btn btn--playing'
  }
/>

​
Compound components

Complex interactions are split into composable parts. A parent manages shared state while children consume it. Each part still renders exactly one element.
Compound components use dot notation off a shared namespace:
<VolumeSlider.Root orientation="vertical">
  <VolumeSlider.Track>
    <VolumeSlider.Fill />
  </VolumeSlider.Track>
  <VolumeSlider.Thumb />
</VolumeSlider.Root>

​
Available components

PlayButton

Plays and pauses the media. Reflects data-paused state.React: <PlayButton> / HTML: <media-play-button>

MuteButton

Toggles mute. Reflects data-muted and data-volume-level state.React: <MuteButton> / HTML: <media-mute-button>

FullscreenButton

Enters and exits fullscreen. Reflects data-fullscreen and data-availability state.React: <FullscreenButton> / HTML: <media-fullscreen-button>

PiPButton

Enters and exits picture-in-picture. Reflects data-pip and data-availability state.React: <PiPButton> / HTML: <media-pip-button>

SeekButton

Seeks forward or backward by a fixed number of seconds via the seconds prop/attribute.React: <SeekButton seconds={10}> / HTML: <media-seek-button seconds="10">

CaptionsButton

Toggles captions and subtitles on or off.React: <CaptionsButton> / HTML: <media-captions-button>

PlaybackRateButton

Cycles through playback rates. Reflects the current data-rate.React: <PlaybackRateButton> / HTML: <media-playback-rate-button>

TimeSlider

Seek slider. Compound component with Root, Track, Fill, Buffer, and Thumb parts.React: <TimeSlider.Root> / HTML: <media-time-slider>

VolumeSlider

Volume slider. Compound component with Root, Track, Fill, and Thumb parts.React: <VolumeSlider.Root> / HTML: <media-volume-slider>

BufferingIndicator

Renders only when the player is buffering.React: <BufferingIndicator> / HTML: <media-buffering-indicator>

Poster

Displays the poster image before playback starts.React: <Poster> / HTML: <media-poster>

Thumbnail

Shows a thumbnail preview image at a given time position.React: <Thumbnail> / HTML: <media-thumbnail>

Controls

Container for control elements. Manages visibility based on user activity.React: <Controls.Root> / HTML: <media-controls>

Time

Displays current time, duration, or remaining time.React: <Time.Value type="current"> / HTML: <media-time type="current">

Tooltip

Accessible tooltip wrapper for labeling controls.React: <Tooltip> / HTML: <media-tooltip>

Popover

Floating panel for secondary controls like volume. Compound component with Root, Trigger, and Popup parts.React: <Popover.Root> / HTML: <media-popover>

Build docs developers (and LLMs) love

Get started for freeTalk to us