Skip to main content
Controls is a compound component that manages the visibility of player controls. It shows controls when the user is active or when the video is paused, and hides them after a short delay when the user becomes inactive.

​
Sub-components

ComponentDescription
Controls.RootRoot container that tracks user activity and manages control visibility.
Controls.GroupLayout group for related controls. Receives role="group" when labeled.
Controls.Root requires the controls feature to be registered with the player.

​
Import

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

​
Basic Usage

import { Controls, PlayButton, MuteButton, TimeSlider } from '@videojs/react';

function PlayerUI() {
  return (
    <Controls.Root className="controls">
      <Controls.Group className="controls-bottom">
        <TimeSlider.Root className="time-slider" />
        <Controls.Group className="controls-row">
          <PlayButton />
          <MuteButton />
        </Controls.Group>
      </Controls.Group>
    </Controls.Root>
  );
}

​
Controls.Root Props

​
children
ReactNode
Child controls or Controls.Group elements to render inside the root container.
​
render
ReactElement | ((props: HTMLProps, state: ControlsRoot.State) => ReactElement | null)
Custom render prop for the root <div> element.
​
className
string | ((state: ControlsRoot.State) => string)
CSS class name or a function that receives state and returns a class name.
​
style
CSSProperties | ((state: ControlsRoot.State) => CSSProperties)
Inline style or a function that receives state and returns a style object.

​
Controls.Group Props

​
children
ReactNode
Child controls to group together.
​
aria-label
string
When provided, the group receives role="group" and this label is announced by screen readers.
​
aria-labelledby
string
Alternative to aria-label. When provided, the group receives role="group".
​
render
ReactElement | ((props: HTMLProps, state: ControlsRoot.State) => ReactElement | null)
Custom render prop for the group <div> element.
​
className
string | ((state: ControlsRoot.State) => string)
CSS class name or a function that receives state and returns a class name.
​
style
CSSProperties | ((state: ControlsRoot.State) => CSSProperties)
Inline style or a function that receives state and returns a style object.

​
State Data Attributes

These attributes are reflected on the Controls.Root element.
AttributeDescription
data-visiblePresent when controls should be visible (user active or video paused).

​
CSS Styling Example

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

​
Behavior

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.

​
Accessibility

No ARIA role is applied to Controls.Root — it is a layout wrapper, not a landmark. Controls.Group automatically receives role="group" only when an aria-label or aria-labelledby attribute is provided.

Build docs developers (and LLMs) love

Get started for freeTalk to us