media-controls
Container component for composing and auto-hiding video player controls on user interaction
Anatomy
Import the component and assemble its parts:
<Controls.Root>
<Controls.Group />
</Controls.Root><media-controls>
<media-controls-group></media-controls-group>
</media-controls>Behavior
If the user is active, or if the video is paused, this component will show controls. Otherwise, it will hide them after a short delay.
User activity is tracked via pointer movement, keyboard input, and focus events on the player container. On touch devices, a quick tap toggles visibility. mouseleave immediately sets the user as inactive.
Styling
By default, controls have the following styles:
/* Click-through: clicks pass through controls to video beneath */
media-controls {
pointer-events: none;
}
media-controls-group {
pointer-events: auto;
}
/* Fade transition */
media-controls {
transition: opacity 0.25s;
}
media-controls:not([data-visible]) {
opacity: 0;
}React renders <div> elements. Add a className to style them:
/* Click-through: clicks pass through controls to video beneath */
.controls {
pointer-events: none;
}
.controls-group {
pointer-events: auto;
}
/* Fade transition */
.controls {
transition: opacity 0.25s;
}
.controls:not([data-visible]) {
opacity: 0;
}Accessibility
No ARIA role is applied to <media-controls> — it is a layout wrapper, not a landmark. <media-controls-group> automatically receives role="group" when an aria-label or aria-labelledby attribute is provided; otherwise no role is assigned.
No ARIA role is applied to Controls.Root — it is a layout wrapper, not a landmark. Controls.Group automatically receives role="group" when an aria-label or aria-labelledby attribute is provided; otherwise no role is assigned.
Examples
Basic Usage
import { Controls, createPlayer, PlayButton, Time } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';
const Player = createPlayer({ features: videoFeatures });
export default function BasicUsage() {
return (
<Player.Provider>
<Player.Container className="media-container">
<Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
<Controls.Root className="media-controls">
<Controls.Group className="controls-group" aria-label="Playback controls">
<PlayButton
className="button"
render={(props, state) => <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>}
/>
<Time.Value type="current" className="time" />
</Controls.Group>
</Controls.Root>
</Player.Container>
</Player.Provider>
);
}
.media-container {
position: relative;
}
.media-container video {
width: 100%;
}
.media-controls {
position: absolute;
inset: 0;
display: flex;
align-items: flex-end;
padding: 12px;
pointer-events: none;
background: linear-gradient(to top, rgba(0, 0, 0, 0.45), transparent 45%);
transition: opacity 0.25s;
}
.media-controls:not([data-visible]) {
opacity: 0;
}
.controls-group {
pointer-events: auto;
}
.time {
display: inline-flex;
gap: 4px;
align-items: center;
padding-block: 8px;
padding-inline: 16px;
font-size: 14px;
color: black;
background: rgba(255, 255, 255, 0.75);
border: 1px solid rgba(255, 255, 255, 0.25);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
.controls-group {
display: flex;
align-items: center;
justify-content: space-between;
width: 100%;
}
.button {
padding-block: 8px;
padding-inline: 16px;
font-size: 14px;
color: black;
cursor: pointer;
background: rgba(255, 255, 255, 0.75);
border: 1px solid rgba(255, 255, 255, 0.25);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
<video-player class="video-player">
<media-container>
<video
src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
autoplay
muted
playsinline
loop
></video>
<media-controls class="media-controls">
<media-controls-group class="controls-group" aria-label="Playback controls">
<media-play-button class="button media-play-button">
<span class="paused">Play</span>
<span class="playing">Pause</span>
</media-play-button>
<media-time class="time" type="current"></media-time>
</media-controls-group>
</media-controls>
</media-container>
</video-player>
.video-player {
position: relative;
display: block;
}
.video-player video {
width: 100%;
}
.media-controls {
position: absolute;
inset: 0;
display: flex;
align-items: flex-end;
padding: 12px;
pointer-events: none;
background: linear-gradient(to top, rgba(0, 0, 0, 0.45), transparent 45%);
transition: opacity 0.25s;
}
.media-controls:not([data-visible]) {
opacity: 0;
}
.controls-group {
pointer-events: auto;
}
.time {
display: inline-flex;
gap: 4px;
align-items: center;
padding-block: 8px;
padding-inline: 16px;
font-size: 14px;
color: black;
background: rgba(255, 255, 255, 0.75);
border: 1px solid rgba(255, 255, 255, 0.25);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
.controls-group {
display: flex;
align-items: center;
justify-content: space-between;
width: 100%;
}
.button {
padding-block: 8px;
padding-inline: 16px;
font-size: 14px;
color: black;
cursor: pointer;
background: rgba(255, 255, 255, 0.75);
border: 1px solid rgba(255, 255, 255, 0.25);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
.button .paused,
.button .playing {
display: none;
}
.media-play-button[data-paused] .paused {
display: inline;
}
.media-play-button:not([data-paused]) .playing {
display: inline;
}
import '@videojs/html/video/player';
import '@videojs/html/ui/controls';
import '@videojs/html/ui/play-button';
import '@videojs/html/ui/time';
API Reference
Rootmedia-controls
Root container for player controls state and rendered control content.
State
State is accessible via the
render, className, and style props.State is reflected as data attributes for CSS styling.
| Property | Type | Details |
|---|---|---|
visible | boolean | |
userActive | boolean |
Data attributes
| Attribute | Type | Details |
|---|---|---|
data-visible | ||
| ||
data-user-active | ||
| ||
Groupmedia-controls-group
Layout group for related controls; sets role="group" when labeled.
Data attributes
| Attribute | Type | Details |
|---|---|---|
data-visible | ||
| ||
data-user-active | ||
| ||