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;
}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.
Examples
Basic Usage
import { Controls, createPlayer, PlayButton, Time } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';
import './BasicUsage.css';
const Player = createPlayer({ features: videoFeatures });
export default function BasicUsage() {
return (
<Player.Provider>
<Player.Container className="react-controls-basic">
<Video
src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
autoPlay
muted
playsInline
loop
/>
<Controls.Root className="react-controls-basic__root">
<Controls.Group className="react-controls-basic__bottom" aria-label="Playback controls">
<PlayButton
className="react-controls-basic__button"
render={(props, state) => <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>}
/>
<Time.Value type="current" className="react-controls-basic__time" />
</Controls.Group>
</Controls.Root>
</Player.Container>
</Player.Provider>
);
}
.react-controls-basic {
position: relative;
}
.react-controls-basic video {
width: 100%;
}
.react-controls-basic__root {
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;
}
.react-controls-basic__root:not([data-visible]) {
opacity: 0;
}
.react-controls-basic__bottom {
pointer-events: auto;
}
.react-controls-basic__time {
display: inline-flex;
align-items: center;
gap: 4px;
padding-block: 8px;
padding-inline: 16px;
border-radius: 9999px;
background: rgba(255, 255, 255, 0.75);
backdrop-filter: blur(10px);
color: black;
border: 1px solid rgba(255, 255, 255, 0.25);
font-size: 14px;
}
.react-controls-basic__bottom {
display: flex;
align-items: center;
justify-content: space-between;
width: 100%;
}
.react-controls-basic__button {
padding-block: 8px;
background: rgba(255, 255, 255, 0.75);
backdrop-filter: blur(10px);
color: black;
border: 1px solid rgba(255, 255, 255, 0.25);
border-radius: 9999px;
padding-inline: 16px;
font-size: 14px;
cursor: pointer;
}
<video-player class="html-controls-basic">
<media-container>
<video
src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
autoplay
muted
playsinline
loop
></video>
<media-controls class="html-controls-basic__root">
<media-controls-group class="html-controls-basic__bottom" aria-label="Playback controls">
<media-play-button class="html-controls-basic__button html-controls-basic__play">
<span class="show-when-paused">Play</span>
<span class="show-when-playing">Pause</span>
</media-play-button>
<media-time class="html-controls-basic__time" type="current"></media-time>
</media-controls-group>
</media-controls>
</media-container>
</video-player>
.html-controls-basic {
display: block;
position: relative;
}
.html-controls-basic video {
width: 100%;
}
.html-controls-basic__root {
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;
}
.html-controls-basic__root:not([data-visible]) {
opacity: 0;
}
.html-controls-basic__bottom {
pointer-events: auto;
}
.html-controls-basic__time {
display: inline-flex;
align-items: center;
gap: 4px;
padding-block: 8px;
padding-inline: 16px;
border-radius: 9999px;
background: rgba(255, 255, 255, 0.75);
backdrop-filter: blur(10px);
color: black;
border: 1px solid rgba(255, 255, 255, 0.25);
font-size: 14px;
}
.html-controls-basic__bottom {
display: flex;
align-items: center;
justify-content: space-between;
width: 100%;
}
.html-controls-basic__button {
padding-block: 8px;
background: rgba(255, 255, 255, 0.75);
backdrop-filter: blur(10px);
color: black;
border: 1px solid rgba(255, 255, 255, 0.25);
border-radius: 9999px;
padding-inline: 16px;
font-size: 14px;
cursor: pointer;
}
.html-controls-basic__button .show-when-paused,
.html-controls-basic__button .show-when-playing {
display: none;
}
.html-controls-basic__play[data-paused] .show-when-paused {
display: inline;
}
.html-controls-basic__play:not([data-paused]) .show-when-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
Root media-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 | |
|---|---|---|
visible | boolean | |
userActive | boolean |
Data attributes
| Attribute | Type | |
|---|---|---|
data-visible | ||
| ||
data-user-active | ||
| ||
Group media-controls-group
Layout group for related controls; sets role="group" when labeled.
Data attributes
| Attribute | Type | |
|---|---|---|
data-visible | ||
| ||
data-user-active | ||
| ||