TimeSlider

A slider component for seeking through media playback time

Anatomy

<TimeSlider.Root />

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.

Seeking is throttled via the commitThrottle prop (default 100ms) to avoid overwhelming the media element during drag operations.

Styling

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

media-time-slider::before {
  width: calc(var(--media-slider-fill) * 1%);
}

Use data-seeking to style during active seek operations:

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

Accessibility

Renders with role="slider" and automatic aria-label of “Seek”. 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

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 { createPlayer, TimeSlider } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

import './WithParts.css';

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

export default function WithParts() {
  return (
    <Player.Provider>
      <Player.Container className="react-time-slider-parts">
        <Video
          src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
          autoPlay
          muted
          playsInline
          loop
        />
        <TimeSlider.Root className="react-time-slider-parts__slider">
          <TimeSlider.Track className="react-time-slider-parts__track">
            <TimeSlider.Buffer className="react-time-slider-parts__buffer" />
            <TimeSlider.Fill className="react-time-slider-parts__fill" />
          </TimeSlider.Track>
          <TimeSlider.Thumb className="react-time-slider-parts__thumb" />
          <TimeSlider.Value type="pointer" className="react-time-slider-parts__value" />
        </TimeSlider.Root>
      </Player.Container>
    </Player.Provider>
  );
}

.react-time-slider-parts {
  position: relative;
}

.react-time-slider-parts video {
  width: 100%;
}

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

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

.react-time-slider-parts__slider[data-interactive] .react-time-slider-parts__track {
  height: 6px;
}

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

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

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

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

.react-time-slider-parts__slider[data-dragging] .react-time-slider-parts__thumb {
  transform: translateX(-50%) scale(1.1);
}

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

.react-time-slider-parts__slider[data-pointing] .react-time-slider-parts__value {
  opacity: 1;
}

<video-player class="html-time-slider-parts">
    <media-container>
        <video
            src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
            autoplay
            muted
            playsinline
            loop
        ></video>
        <media-time-slider class="html-time-slider-parts__slider">
            <media-slider-track class="html-time-slider-parts__track">
                <media-slider-buffer class="html-time-slider-parts__buffer"></media-slider-buffer>
                <media-slider-fill class="html-time-slider-parts__fill"></media-slider-fill>
            </media-slider-track>
            <media-slider-thumb class="html-time-slider-parts__thumb"></media-slider-thumb>
            <media-slider-value type="pointer" class="html-time-slider-parts__value"></media-slider-value>
        </media-time-slider>
    </media-container>
</video-player>

.html-time-slider-parts,
.html-time-slider-parts media-container {
  display: block;
  position: relative;
}

.html-time-slider-parts video {
  width: 100%;
}

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

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

.html-time-slider-parts__slider[data-interactive] .html-time-slider-parts__track {
  height: 6px;
}

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

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

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

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

.html-time-slider-parts__slider[data-dragging] .html-time-slider-parts__thumb {
  transform: translateX(-50%) scale(1.1);
}

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

.html-time-slider-parts__slider[data-pointing] .html-time-slider-parts__value {
  opacity: 1;
}

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

API Reference

Root

Props

Prop	Type	Default
`commitThrottle`	`number`	`100`
Description Trailing-edge throttle (ms) for seek requests during drag.
`disabled`	`boolean`	`—`
Description Whether the slider is non-interactive.
`label`	`string \| function`	`'Seek'`
Description Custom label for the slider. Type `string \| ((state: SliderState) => string)`
`largeStep`	`number`	`—`
Description Large step increment (Page Up/Down keys).
`max`	`number`	`—`
`min`	`number`	`—`
`orientation`	`'horizontal' \| 'vertical'`	`—`
Description Axis of slider movement.
`step`	`number`	`—`
Description Step increment for value changes (arrow keys).
`thumbAlignment`	`'center' \| 'edge'`	`—`
Description How the thumb aligns at the track edges. `edge` constrains the thumb within track bounds.
`value`	`number`	`—`

State

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

Property	Type
`bufferPercent`	`number`
Description Buffered amount as a percentage of duration (0–100).
`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 or pointing 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.
`duration`	`number`
Description Total duration in seconds (0 if unknown).
`currentTime`	`number`
Description Current playback position in seconds.
`seeking`	`boolean`
Description Whether a seek operation is in progress.

Data attributes

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

CSS custom properties

Variable
`--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.

Buffer

Displays the buffered range on the slider track.

Fill

Displays the filled portion from start to the current value.

Preview

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

Props

Prop	Type	Default
`overflow`	`SliderPreviewOverflow`	`—`
Description How the preview handles the slider boundaries. `'clamp'` keeps the preview within bounds, `'visible'` allows it to extend beyond the edges.

Data attributes

Attribute	Type
`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 or pointing 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.

Thumb

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

Data attributes

Attribute	Type
`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 or pointing 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.

Track

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

Value

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

Props

Prop	Type	Default
`format`	`((value: number) => string)`	`—`
Description Custom formatter for the displayed value. Overrides the root's `formatValue`.
`type`	`"current" \| "pointer"`	`—`
Description Which slider value to display: the current position or the pointer position.

Data attributes

Attribute	Type
`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 or pointing 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.

Anatomy

Behavior

Styling

Accessibility

Examples

API Reference

Root media-time-slider

Props

State

Data attributes

CSS custom properties

Buffer media-slider-buffer

Fill media-slider-fill

Preview media-slider-preview

Props

Data attributes

Thumb media-slider-thumb

Data attributes

Track media-slider-track

Value media-slider-value

Props

Data attributes

Root

Buffer

Fill

Preview

Thumb

Track

Value