Skip to content

ReferenceLayout

Controls

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

Import

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

Anatomy

Import the component and assemble its parts:

<Controls.Root>
  <Controls.Backdrop />
  <Controls.Content>
    <Controls.Group />
  </Controls.Content>
</Controls.Root>

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.

<Controls.Root visibility="always">
  <Controls.Content>...</Controls.Content>
</Controls.Root>

Styling

Controls.Root is a state and context provider. Controls.Content renders the interactive controls surface and receives its DOM props, ref, and controls state data attributes.

Controls.Backdrop is an optional presentational sibling of 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:

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;
}

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

/* Fade transition */
.controls {
  transition: opacity 0.25s;
}

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

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

Accessibility

Controls.Root renders no element. No ARIA role is applied to Controls.Content because it is a layout surface, not a landmark. Controls.Backdrop is always hidden from assistive technology. 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 { Container, 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>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />

        <Controls.Root>
          <Controls.Backdrop className="controls-backdrop" />
          <Controls.Content 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.Content>
        </Controls.Root>
      </Container>
    </Player>
  );
}

API Reference

Root

Manages controls state and provides it to the compound parts. Does not render an element.

Props

PropTypeDefaultDetails
visibility'auto' | 'always''auto'

State

State is accessible via the render, className, and style props.

PropertyTypeDetails
visibleboolean
userActiveboolean

Data attributes

AttributeDescription
data-visiblePresent when controls are visible.
data-user-activePresent when the user has recently interacted.

Backdrop

Presentational layer behind player controls. Renders a <div> with the controls state data attributes so skins can style it without reaching across sibling components.

Props

PropTypeDefaultDetails
classNamestring | function—
renderReactElement | function—
styleCSSProperties | function—

Data attributes

AttributeDescription
data-visiblePresent when controls are visible.
data-user-activePresent when the user has recently interacted.

Content

Renders the interactive controls surface.

Props

PropTypeDefaultDetails
classNamestring | function—
renderReactElement | function—
styleCSSProperties | function—

Data attributes

AttributeDescription
data-visiblePresent when controls are visible.
data-user-activePresent when the user has recently interacted.

Group

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

Props

PropTypeDefaultDetails
classNamestring | function—
renderReactElement | function—
styleCSSProperties | function—

Data attributes

AttributeDescription
data-visiblePresent when controls are visible.
data-user-activePresent when the user has recently interacted.