Skip to content
FrameworkStyle

TimeSlider

A slider component for seeking through media playback time

Import

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

Anatomy

<TimeSlider.Root>
  <TimeSlider.Track>
    <TimeSlider.Buffer />
    <TimeSlider.Fill />
  </TimeSlider.Track>
  <TimeSlider.Thumb />
  <TimeSlider.Preview>
    <TimeSlider.ChapterTitle />
    <TimeSlider.Value type="pointer" />
  </TimeSlider.Preview>
</TimeSlider.Root>

Add Chapters to divide the slider track into sections. Each cue in the default kind="chapters" text track marks a chapter. Without chapter cues, one section covers the full slider.

<TimeSlider.Chapters
  renderChapter={(props, state) => (
    <div {...props}>
      <TimeSlider.Track>
        <TimeSlider.Buffer />
        <TimeSlider.Fill />
      </TimeSlider.Track>
    </div>
  )}
/>

renderChapter receives the attributes, styles, and state for each normalized chapter range. When no chapter cues are available, it renders once as a full-width, cue-less range.

Behavior

Displays and controls the current playback position. Dragging the slider seeks the media. The fill level reflects currentTime / duration as a percentage, and the buffer level shows how much media has been buffered.

Value changes during drag are throttled via the changeThrottle prop (default 100ms) using a leading+trailing throttle to keep the UI responsive without overwhelming the media element.

Chapter cues are normalized into contiguous ranges. Any uncovered time becomes a gap range, so track geometry always spans the full duration. With no usable chapter cues, one gap range spans the entire slider. Gap ranges receive the same geometry styles but cannot be highlighted and have no chapter title.

Styling

Use CSS custom properties to style the fill, pointer, and buffer levels:

React renders a <div> element. Add a className to style it:

.time-slider::before {
  width: var(--media-slider-fill);
}

Use data-seeking to style during active seek operations:

.time-slider[data-seeking] {
  opacity: 0.8;
}

Each rendered chapter receives data-active while playback is inside it and data-highlighted while the pointer is inside an authored chapter. Its geometry and local progress are exposed through:

  • --media-slider-chapter-start
  • --media-slider-chapter-end
  • --media-slider-chapter-width
  • --media-slider-chapter-fill
  • --media-slider-chapter-buffer

The generated fill and buffer parts also inherit the slider-level --media-slider-fill and --media-slider-buffer values. This allows every chapter to render full-width progress planes and use its chapter bounds as a clip, keeping progress transitions continuous across segments.

Accessibility

Renders with role="slider" and an automatic aria-label that resolves to “Seek” from the active locale. Override with the label prop. Keyboard controls:

  • Arrow Left / Arrow Right: step by step increment
  • Page Up / Page Down: step by largeStep increment
  • Home: seek to start
  • End: seek to end

ChapterTitle follows the pointer during pointer interaction. While the slider has keyboard focus, it follows the current playback position and announces chapter changes.

Examples

Nest sub-components for full control over the slider’s DOM structure. This example includes a track, fill bar, buffer indicator, draggable thumb, and a tooltip that shows the pointed-at time.

0:00
import { Container, createPlayer, TimeSlider } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function WithParts() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <TimeSlider.Root className="media-time-slider">
          <TimeSlider.Track className="media-slider-track">
            <TimeSlider.Buffer className="media-slider-buffer" />
            <TimeSlider.Fill className="media-slider-fill" />
          </TimeSlider.Track>
          <TimeSlider.Thumb className="media-slider-thumb" />
          <TimeSlider.Value type="pointer" className="media-slider-value" />
        </TimeSlider.Root>
      </Container>
    </Player>
  );
}

With chapters

Add a default chapters track, then provide the markup used for each chapter. The deliberate one-minute gap in this example remains visible as an unlabelled, non-highlightable segment.

0:00
import { Container, createPlayer, TimeSlider } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function WithChapters() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop crossOrigin="anonymous">
          <track kind="chapters" src="/docs/demos/time-slider/chapters.vtt" srcLang="en" default />
        </Video>
        <TimeSlider.Root className="media-time-slider">
          <TimeSlider.Chapters
            className="media-slider-chapters"
            renderChapter={(props) => (
              <div {...props} className="media-slider-chapter">
                <TimeSlider.Track className="media-slider-track">
                  <TimeSlider.Buffer className="media-slider-buffer" />
                  <TimeSlider.Fill className="media-slider-fill" />
                </TimeSlider.Track>
              </div>
            )}
          />
          <TimeSlider.Thumb className="media-slider-thumb" />
          <TimeSlider.Preview className="media-slider-preview">
            <TimeSlider.ChapterTitle className="media-slider-chapter-title" />
            <TimeSlider.Value type="pointer" />
          </TimeSlider.Preview>
        </TimeSlider.Root>
      </Container>
    </Player>
  );
}

API Reference

Root

Props

PropTypeDefaultDetails
changeThrottlenumber100
disabledboolean—
labelobject''
largeStepnumber—
maxnumber—
minnumber—
orientation'horizontal' | 'vertical'—
pauseOnDragbooleanfalse
stepnumber—
thumbAlignment'center' | 'edge'—
valuenumber—

State

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

PropertyTypeDetails
valuenumber
fillPercentnumber
pointerPercentnumber
draggingboolean
pointingboolean
interactiveboolean
orientation'horizontal' | 'vertical'
disabledboolean
thumbAlignment'center' | 'edge'
currentTimenumber
durationnumber
seekingboolean
bufferPercentnumber

Data attributes

AttributeTypeDetails
data-seeking

CSS custom properties

VariableDetails
--media-slider-fill
--media-slider-pointer
--media-slider-buffer

ChapterTitle

Displays the chapter title at the current pointer or keyboard position.

Props

PropTypeDefaultDetails
classNamestring | ((state: TimeSliderChapterTitleState) => string | undefined)—
renderReactElement | ((props: HTMLProps, state: TimeSliderChapterTitleState) => ReactElement | null)—
styleCSSProperties | ((state: TimeSliderChapterTitleState) => CSSProperties | undefined)—

Chapters

Renders normalized chapter ranges across the full slider, including one full range when chapter cues are absent.

Props

PropTypeDefaultDetails
classNamestring | ((state: TimeSliderChaptersState) => string | undefined)—
renderReactElement | ((props: HTMLProps, state: TimeSliderChaptersState) => ReactElement | null)—
renderChapter((props: Omit<HTMLProps<HTMLElement>, 'ref'>, state: TimeSliderChapterState) => ReactElement)—
styleCSSProperties | ((state: TimeSliderChaptersState) => CSSProperties | undefined)—

Buffer

Displays the buffered range on the slider track.

Props

PropTypeDefaultDetails
classNamestring | ((state: SliderState) => string | undefined)—
renderReactElement | ((props: HTMLProps, state: SliderState) => ReactElement | null)—
styleCSSProperties | ((state: SliderState) => CSSProperties | undefined)—

Fill

Displays the filled portion from start to the current value.

Props

PropTypeDefaultDetails
classNamestring | ((state: SliderState) => string | undefined)—
renderReactElement | ((props: HTMLProps, state: SliderState) => ReactElement | null)—
styleCSSProperties | ((state: SliderState) => CSSProperties | undefined)—

Preview

Positioning container for preview content that tracks the pointer along the slider.

Props

PropTypeDefaultDetails
classNamestring | ((state: SliderState) => string | undefined)—
renderReactElement | ((props: HTMLProps, state: SliderState) => ReactElement | null)—
styleCSSProperties | ((state: SliderState) => CSSProperties | undefined)—

Data attributes

AttributeTypeDetails
data-dragging
data-pointing
data-interactive
data-orientation'horizontal' | 'vertical'
data-disabled

Thumb

Draggable handle for setting the slider value. Receives focus and handles keyboard interaction.

Props

PropTypeDefaultDetails
classNamestring | ((state: SliderState) => string | undefined)—
renderReactElement | ((props: HTMLProps, state: SliderState) => ReactElement | null)—
styleCSSProperties | ((state: SliderState) => CSSProperties | undefined)—

Data attributes

AttributeTypeDetails
data-dragging
data-pointing
data-interactive
data-orientation'horizontal' | 'vertical'
data-disabled

Track

Contains the slider's visual track and interactive hit zone.

Props

PropTypeDefaultDetails
classNamestring | ((state: SliderState) => string | undefined)—
renderReactElement | ((props: HTMLProps, state: SliderState) => ReactElement | null)—
styleCSSProperties | ((state: SliderState) => CSSProperties | undefined)—

Value

Displays a formatted text representation of the slider value. Renders an <output> element.

Props

PropTypeDefaultDetails
classNamestring | ((state: SliderState) => string | undefined)—
format((value: number) => string)—
renderReactElement | ((props: HTMLProps, state: SliderState) => ReactElement | null)—
styleCSSProperties | ((state: SliderState) => CSSProperties | undefined)—
type'current' | 'pointer'—

Data attributes

AttributeTypeDetails
data-dragging
data-pointing
data-interactive
data-orientation'horizontal' | 'vertical'
data-disabled