ReferenceLayout

media-controls

Container component for composing and auto-hiding video player controls on user interaction

Import

import '@videojs/html/ui/controls';
import '@videojs/html/ui/controls-backdrop';
import '@videojs/html/ui/controls-content';
import '@videojs/html/ui/controls-group';

Anatomy

Import the component and assemble its parts:

<media-controls>
  <media-controls-backdrop></media-controls-backdrop>
  <media-controls-content>
    <media-controls-group></media-controls-group>
  </media-controls-content>
</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.

visibility selects between the two modes. The default, auto, follows the player’s controls visibility state as described above. always keeps the controls visible and reports the user as active regardless of playback or idle state, and works without the controls feature. The idle delay itself is not configurable.

<media-controls visibility="always">
  <media-controls-content>...</media-controls-content>
</media-controls>

Styling

<media-controls> is a state and context provider that also reflects the controls state data attributes. <media-controls-content> is the interactive controls surface and receives the same controls state data attributes.

<media-controls-backdrop> is an optional presentational sibling of <media-controls-content>. It receives the same controls state data attributes, allowing its styling and transitions to be authored independently from the controls surface.

By default, controls have the following styles:

/* Click-through: clicks pass through controls to video beneath */
media-controls-content {
  pointer-events: none;
}

media-controls-group {
  pointer-events: auto;
}

media-controls-backdrop {
  position: absolute;
  inset: 0;
  transition: opacity 0.35s;
}

/* Fade transition */
media-controls-content {
  transition: opacity 0.25s;
}

media-controls-content:not([data-visible]) {
  opacity: 0;
}

media-controls-backdrop:not([data-visible]) {
  opacity: 0;
}

Accessibility

No ARIA role is applied to <media-controls> or <media-controls-content> — they provide state and layout, not a landmark. <media-controls-backdrop> is always hidden from assistive technology. <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

Play Pause

<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>

    <media-controls>
      <media-controls-backdrop class="controls-backdrop"></media-controls-backdrop>
      <media-controls-content 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-content>
    </media-controls>
  </media-container>
</video-player>

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

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

.media-controls {
  position: absolute;
  inset: 0;
  display: flex;
  align-items: flex-end;
  padding: 12px;
  pointer-events: none;
  transition: opacity 0.25s;
}

.controls-backdrop {
  position: absolute;
  inset: 0;
  pointer-events: none;
  background: linear-gradient(to top, rgba(0, 0, 0, 0.45), transparent 45%);
  opacity: 1;
  transition: opacity 0.35s;
}

.controls-backdrop:not([data-visible]),
.media-controls:not([data-visible]) {
  opacity: 0;
}

.controls-group {
  display: flex;
  align-items: center;
  justify-content: space-between;
  width: 100%;
  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);
}

.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/container';
import '@videojs/html/ui/controls';
import '@videojs/html/ui/controls-backdrop';
import '@videojs/html/ui/controls-content';
import '@videojs/html/ui/controls-group';
import '@videojs/html/ui/play-button';
import '@videojs/html/ui/time';

API Reference

media-controls

Tracks controls visibility, reflects it as data attributes, and shares it with its descendant controls parts. Hiding the controls closes any popup open inside it.

Props

Prop	Type	Default	Details
`visibility`	`'auto' \| 'always'`	`'auto'`
Description Whether controls follow player visibility state or remain visible.

State

State is reflected as data attributes for CSS styling.

Property	Type	Details
`visible`	`boolean`
Description Whether the controls are visible.
`userActive`	`boolean`
Description Whether the user has recently interacted with the player.

Data attributes

Attribute	Description
`data-visible`	Present when controls are visible.
`data-user-active`	Present when the user has recently interacted.

media-controls-backdrop

Presentational backdrop that reflects its owning controls surface's state.

Data attributes

Attribute	Description
`data-visible`	Present when controls are visible.
`data-user-active`	Present when the user has recently interacted.

media-controls-content

Interactive surface that reflects its owning controls state.

Data attributes

Attribute	Description
`data-visible`	Present when controls are visible.
`data-user-active`	Present when the user has recently interacted.

media-controls-group

Layout group for related controls; sets role="group" when labeled.

Data attributes

Attribute	Description
`data-visible`	Present when controls are visible.
`data-user-active`	Present when the user has recently interacted.