FrameworkStyle

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>

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:

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

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

API Reference

Root

Root container for player controls state and rendered control content.

State

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

Property Type Details
visible boolean
userActive boolean

Data attributes

Attribute Type Details
data-visible
data-user-active

Group

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

Data attributes

Attribute Type Details
data-visible
data-user-active