media-time-slider

A slider component for seeking through media playback time

Import

import '@videojs/html/ui/time-slider';

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>

<media-time-slider>
  <media-slider-track>
    <media-slider-buffer></media-slider-buffer>
    <media-slider-fill></media-slider-fill>
  </media-slider-track>
  <media-slider-thumb></media-slider-thumb>
  <media-slider-preview>
    <media-time-slider-chapter-title></media-time-slider-chapter-title>
    <media-slider-value type="pointer"></media-slider-value>
  </media-slider-preview>
</media-time-slider>

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.

<media-time-slider-chapters>
  <template>
    <div>
      <media-slider-track>
        <media-slider-buffer></media-slider-buffer>
        <media-slider-fill></media-slider-fill>
      </media-slider-track>
    </div>
  </template>
</media-time-slider-chapters>

The required template must contain exactly one HTML root element. It remains in the light DOM and is cloned for each normalized chapter range. When no chapter cues are available, it is cloned 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:

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

Use data-seeking to style during active seek operations:

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

.media-container {
  position: relative;
}

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

.media-time-slider {
  position: absolute;
  right: 0;
  bottom: 0;
  left: 0;
  display: flex;
  align-items: center;
  height: 20px;
  cursor: pointer;
}

.media-slider-track {
  position: absolute;
  right: 0;
  left: 0;
  height: 4px;
  background: rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  transition: height 150ms ease;
}

.media-time-slider[data-interactive] .media-slider-track {
  height: 6px;
}

.media-slider-buffer {
  position: absolute;
  top: 0;
  left: 0;
  width: var(--media-slider-buffer);
  height: 100%;
  background: rgba(255, 255, 255, 0.4);
  border-radius: 9999px;
}

.media-slider-fill {
  position: absolute;
  top: 0;
  left: 0;
  width: var(--media-slider-fill);
  height: 100%;
  background: white;
  border-radius: 9999px;
}

.media-slider-thumb {
  position: absolute;
  left: var(--media-slider-fill);
  width: 14px;
  height: 14px;
  background: white;
  border-radius: 50%;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
  transform: translateX(-50%) scale(0);
  transition: transform 150ms ease;
}

.media-time-slider[data-interactive] .media-slider-thumb {
  transform: translateX(-50%) scale(1);
}

.media-time-slider[data-dragging] .media-slider-thumb {
  left: var(--media-slider-pointer);
  transform: translateX(-50%) scale(1.1);
}

.media-time-slider[data-dragging] .media-slider-fill {
  width: var(--media-slider-pointer);
}

.media-slider-value {
  position: absolute;
  bottom: 100%;
  left: var(--media-slider-pointer);
  padding: 2px 6px;
  margin-bottom: 6px;
  font-size: 12px;
  color: white;
  white-space: nowrap;
  pointer-events: none;
  background: rgba(0, 0, 0, 0.8);
  border-radius: 4px;
  opacity: 0;
  transform: translateX(-50%);
  transition: opacity 150ms ease;
}

.media-time-slider[data-pointing] .media-slider-value {
  opacity: 1;
}

<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <media-time-slider class="media-time-slider">
      <media-slider-track class="media-slider-track">
        <media-slider-buffer class="media-slider-buffer"></media-slider-buffer>
        <media-slider-fill class="media-slider-fill"></media-slider-fill>
      </media-slider-track>
      <media-slider-thumb class="media-slider-thumb"></media-slider-thumb>
      <media-slider-value type="pointer" class="media-slider-value"></media-slider-value>
    </media-time-slider>
  </media-container>
</video-player>

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

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

.media-time-slider {
  position: absolute;
  right: 0;
  bottom: 0;
  left: 0;
  display: flex;
  align-items: center;
  height: 20px;
  cursor: pointer;
}

.media-slider-track {
  position: absolute;
  right: 0;
  left: 0;
  height: 4px;
  background: rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  transition: height 150ms ease;
}

.media-time-slider[data-interactive] .media-slider-track {
  height: 6px;
}

.media-slider-buffer {
  position: absolute;
  top: 0;
  left: 0;
  width: var(--media-slider-buffer);
  height: 100%;
  background: rgba(255, 255, 255, 0.4);
  border-radius: 9999px;
}

.media-slider-fill {
  position: absolute;
  top: 0;
  left: 0;
  width: var(--media-slider-fill);
  height: 100%;
  background: white;
  border-radius: 9999px;
}

.media-slider-thumb {
  position: absolute;
  left: var(--media-slider-fill);
  width: 14px;
  height: 14px;
  background: white;
  border-radius: 50%;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
  transform: translateX(-50%) scale(0);
  transition: transform 150ms ease;
}

.media-time-slider[data-interactive] .media-slider-thumb {
  transform: translateX(-50%) scale(1);
}

.media-time-slider[data-dragging] .media-slider-thumb {
  left: var(--media-slider-pointer);
  transform: translateX(-50%) scale(1.1);
}

.media-time-slider[data-dragging] .media-slider-fill {
  width: var(--media-slider-pointer);
}

.media-slider-value {
  position: absolute;
  bottom: 100%;
  left: var(--media-slider-pointer);
  padding: 2px 6px;
  margin-bottom: 6px;
  font-size: 12px;
  color: white;
  white-space: nowrap;
  pointer-events: none;
  background: rgba(0, 0, 0, 0.8);
  border-radius: 4px;
  opacity: 0;
  transform: translateX(-50%);
  transition: opacity 150ms ease;
}

.media-time-slider[data-pointing] .media-slider-value {
  opacity: 1;
}

import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/time-slider';

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

.media-container {
  position: relative;
}

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

.media-time-slider {
  position: absolute;
  right: 12px;
  bottom: 8px;
  left: 12px;
  display: flex;
  align-items: center;
  height: 20px;
  color: white;
  cursor: pointer;
}

.media-slider-chapters {
  position: relative;
  width: 100%;
  height: 100%;
}

.media-slider-chapter {
  position: absolute;
  inset: 0;
  display: flex;
  align-items: center;
  clip-path: inset(0 calc(100% - var(--media-slider-chapter-end)) 0 var(--media-slider-chapter-start));
}

.media-slider-track {
  position: absolute;
  right: 0;
  left: 0;
  height: 4px;
  overflow: hidden;
  background: rgb(255 255 255 / 30%);
  border-radius: 9999px;
  transition: height 150ms ease;
}

.media-slider-chapter .media-slider-track {
  clip-path: inset(
    0 calc(100% - var(--media-slider-chapter-end) + 2px) 0 calc(var(--media-slider-chapter-start) + 2px) round 9999px
  );
}

.media-slider-chapter[data-highlighted] .media-slider-track {
  height: 7px;
}

.media-slider-buffer,
.media-slider-fill {
  position: absolute;
  inset-block: 0;
  left: 0;
  border-radius: inherit;
  transition: width 200ms linear;
}

.media-slider-buffer {
  width: var(--media-slider-buffer);
  background: rgb(255 255 255 / 30%);
}

.media-slider-fill {
  width: var(--media-slider-fill);
  background: white;
}

.media-time-slider[data-dragging] .media-slider-fill {
  width: var(--media-slider-pointer);
  transition-duration: 0ms;
}

.media-slider-thumb {
  position: absolute;
  top: 50%;
  left: var(--media-slider-fill);
  width: 12px;
  height: 12px;
  background: white;
  border-radius: 50%;
  translate: -50% -50%;
}

.media-time-slider[data-dragging] .media-slider-thumb {
  left: var(--media-slider-pointer);
}

.media-slider-preview {
  position: absolute;
  bottom: 100%;
  left: var(--media-slider-pointer);
  display: flex;
  gap: 6px;
  padding: 3px 7px;
  color: white;
  white-space: nowrap;
  pointer-events: none;
  background: rgb(0 0 0 / 80%);
  border-radius: 4px;
  opacity: 0;
  translate: -50% -4px;
}

.media-time-slider[data-pointing] .media-slider-preview,
.media-time-slider[data-interactive]:not([data-pointing]) .media-slider-preview {
  opacity: 1;
}

.media-slider-chapter-title:empty {
  display: none;
}

<video-player class="video-player">
  <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>
    <media-time-slider class="media-time-slider">
      <media-time-slider-chapters class="media-slider-chapters">
        <template>
          <div class="media-slider-chapter">
            <media-slider-track class="media-slider-track">
              <media-slider-buffer class="media-slider-buffer"></media-slider-buffer>
              <media-slider-fill class="media-slider-fill"></media-slider-fill>
            </media-slider-track>
          </div>
        </template>
      </media-time-slider-chapters>
      <media-slider-thumb class="media-slider-thumb"></media-slider-thumb>
      <media-slider-preview class="media-slider-preview">
        <media-time-slider-chapter-title class="media-slider-chapter-title"></media-time-slider-chapter-title>
        <media-slider-value type="pointer"></media-slider-value>
      </media-slider-preview>
    </media-time-slider>
  </media-container>
</video-player>

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

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

.media-time-slider {
  position: absolute;
  right: 12px;
  bottom: 8px;
  left: 12px;
  display: flex;
  align-items: center;
  height: 20px;
  color: white;
  cursor: pointer;
}

.media-slider-chapters {
  position: relative;
  display: block;
  width: 100%;
  height: 100%;
}

.media-slider-chapter {
  position: absolute;
  inset: 0;
  display: flex;
  align-items: center;
  clip-path: inset(0 calc(100% - var(--media-slider-chapter-end)) 0 var(--media-slider-chapter-start));
}

.media-slider-track {
  position: absolute;
  right: 0;
  left: 0;
  display: block;
  height: 4px;
  overflow: hidden;
  background: rgb(255 255 255 / 30%);
  border-radius: 9999px;
  transition: height 150ms ease;
}

.media-slider-chapter .media-slider-track {
  clip-path: inset(
    0 calc(100% - var(--media-slider-chapter-end) + 2px) 0 calc(var(--media-slider-chapter-start) + 2px) round 9999px
  );
}

.media-slider-chapter[data-highlighted] .media-slider-track {
  height: 7px;
}

.media-slider-buffer,
.media-slider-fill {
  position: absolute;
  inset-block: 0;
  left: 0;
  display: block;
  border-radius: inherit;
  transition: width 200ms linear;
}

.media-slider-buffer {
  width: var(--media-slider-buffer);
  background: rgb(255 255 255 / 30%);
}

.media-slider-fill {
  width: var(--media-slider-fill);
  background: white;
}

.media-time-slider[data-dragging] .media-slider-fill {
  width: var(--media-slider-pointer);
  transition-duration: 0ms;
}

.media-slider-thumb {
  position: absolute;
  top: 50%;
  left: var(--media-slider-fill);
  display: block;
  width: 12px;
  height: 12px;
  background: white;
  border-radius: 50%;
  translate: -50% -50%;
}

.media-time-slider[data-dragging] .media-slider-thumb {
  left: var(--media-slider-pointer);
}

.media-slider-preview {
  position: absolute;
  bottom: 100%;
  left: var(--media-slider-pointer);
  display: flex;
  gap: 6px;
  padding: 3px 7px;
  color: white;
  white-space: nowrap;
  pointer-events: none;
  background: rgb(0 0 0 / 80%);
  border-radius: 4px;
  opacity: 0;
  translate: -50% -4px;
}

.media-time-slider[data-pointing] .media-slider-preview,
.media-time-slider[data-interactive]:not([data-pointing]) .media-slider-preview {
  opacity: 1;
}

.media-slider-chapter-title:empty {
  display: none;
}

import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/time-slider';
import '@videojs/html/ui/time-slider-chapters';

API Reference

media-time-slider

Props

Prop	Type	Default
`changeThrottle`	`number`	`100`
Attribute `change-throttle` Description Leading+trailing throttle (ms) for `onValueChange` during drag.
`disabled`	`boolean`	`—`
Attribute `disabled` Description Whether the slider is non-interactive.
`label`	`object`	`''`
Attribute `label` Description Custom label for the slider. Type `{ key: string; text: string } \| string \| ((state: SliderState) => Text \| string)`
`largeStep`	`number`	`—`
Attribute `large-step` Description Large step increment (Page Up/Down keys).
`max`	`number`	`—`
Attribute `max`
`min`	`number`	`—`
Attribute `min`
`orientation`	`'horizontal' \| 'vertical'`	`—`
Attribute `orientation` Description Axis of slider movement.
`pauseOnDrag`	`boolean`	`false`
Attribute `pause-on-drag` Description When true, pause playback while the user is dragging the thumb, resuming on release if it was playing before.
`step`	`number`	`—`
Attribute `step` Description Step increment for value changes (arrow keys).
`thumbAlignment`	`'center' \| 'edge'`	`—`
Attribute `thumb-alignment` Description How the thumb aligns at the track edges. `edge` constrains the thumb within track bounds.
`value`	`number`	`—`
Attribute `value`

State

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

State is reflected as data attributes for CSS styling.

Property	Type	Details
`value`	`number`
Description Current slider value in the min–max range.
`fillPercent`	`number`
Description Fill level as a percentage (0–100), derived from value.
`pointerPercent`	`number`
Description Pointer position as a percentage of the track (0–100).
`dragging`	`boolean`
Description Whether the user is actively dragging.
`pointing`	`boolean`
Description Whether the pointer is over the slider.
`interactive`	`boolean`
Description Whether dragging, pointing, or focus is active.
`orientation`	`'horizontal' \| 'vertical'`
Description Axis of slider movement.
`disabled`	`boolean`
Description Whether the slider is non-interactive.
`thumbAlignment`	`'center' \| 'edge'`
Description How the thumb aligns at the track edges.
`currentTime`	`number`
Description Current playback position in seconds.
`duration`	`number`
Description Total duration in seconds (0 if unknown).
`seeking`	`boolean`
Description Whether a seek operation is in progress.
`bufferPercent`	`number`
Description Buffered amount as a percentage of duration (0–100).

Data attributes

Attribute	Type	Details
`data-seeking`
Description Present when a seek operation is in progress.

CSS custom properties

Variable	Details
`--media-slider-fill`
Description Fill level percentage (0–100), representing current playback position.
`--media-slider-pointer`
Description Pointer position percentage (0–100), tracking the cursor along the slider.
`--media-slider-buffer`
Description Buffer level percentage (0–100), indicating how much media has been buffered.

Events

Event	Description
`drag-end`	Fired when a pointer drag ends.
`drag-start`	Fired when a pointer drag starts.

media-time-slider-chapter-title

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

media-time-slider-chapters

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

media-slider-buffer

Displays the buffered range on the slider track.

media-slider-fill

Displays the filled portion from start to the current value.

media-slider-preview

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

Data attributes

Attribute	Type	Details
`data-dragging`
Description Present when the user is actively dragging.
`data-pointing`
Description Present when the pointer is over the slider.
`data-interactive`
Description Present when dragging, pointing, or focus is active.
`data-orientation`	`'horizontal' \| 'vertical'`
Description Current axis of slider movement (`horizontal` or `vertical`).
`data-disabled`
Description Present when the slider is non-interactive.

media-slider-thumb

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

Data attributes

Attribute	Type	Details
`data-dragging`
Description Present when the user is actively dragging.
`data-pointing`
Description Present when the pointer is over the slider.
`data-interactive`
Description Present when dragging, pointing, or focus is active.
`data-orientation`	`'horizontal' \| 'vertical'`
Description Current axis of slider movement (`horizontal` or `vertical`).
`data-disabled`
Description Present when the slider is non-interactive.

media-slider-track

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

media-slider-value

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

Props

Prop	Type	Default	Details
`type`	`'current' \| 'pointer'`	`—`
Attribute `type` Description Which slider value to display: the current position or the pointer position.

Data attributes

Attribute	Type	Details
`data-dragging`
Description Present when the user is actively dragging.
`data-pointing`
Description Present when the pointer is over the slider.
`data-interactive`
Description Present when dragging, pointing, or focus is active.
`data-orientation`	`'horizontal' \| 'vertical'`
Description Current axis of slider movement (`horizontal` or `vertical`).
`data-disabled`
Description Present when the slider is non-interactive.

Import

Anatomy

Behavior

Styling

Accessibility

Examples

With chapters

API Reference

Rootmedia-time-slider

Props

State

Data attributes

CSS custom properties

Events

ChapterTitlemedia-time-slider-chapter-title

Chaptersmedia-time-slider-chapters

Buffermedia-slider-buffer

Fillmedia-slider-fill

Previewmedia-slider-preview

Data attributes

Thumbmedia-slider-thumb

Data attributes

Trackmedia-slider-track

Valuemedia-slider-value

Props

Data attributes

media-time-slider

media-time-slider-chapter-title

media-time-slider-chapters

media-slider-buffer

media-slider-fill

media-slider-preview

media-slider-thumb

media-slider-track

media-slider-value