ef-scrubber

Timeline scrubber control for navigating playback time. Supports both horizontal progress bar mode and vertical timeline mode with zoom.

Basic Usage

Horizontal scrubber with progress bar.

<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black" id="scrubber-demo">
  <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" class="size-full object-contain"></ef-video>
</ef-timegroup>
<div class="flex flex-col gap-2 p-4 bg-gray-900 rounded-lg mt-4">
  <ef-scrubber target="scrubber-demo"></ef-scrubber>
  <ef-controls target="scrubber-demo" class="flex gap-2 items-center">
    <ef-toggle-play class="px-3 py-1 bg-blue-600 text-white rounded"></ef-toggle-play>
    <ef-time-display class="text-white text-sm"></ef-time-display>
  </ef-controls>
</div>

Vertical Timeline Mode

Vertical scrubber displays a playhead line that moves across a timeline. Used in ef-timeline and ef-filmstrip components.

<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black" id="vertical-demo">
  <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" class="size-full object-contain"></ef-video>
</ef-timegroup>
<div class="mt-4 h-[120px] relative overflow-hidden bg-gray-900 rounded-lg">
  <ef-scrubber
    target="vertical-demo"
    orientation="vertical"
    zoom-scale="2"
    class="absolute inset-0"
  ></ef-scrubber>
  <div class="absolute top-0 left-0 right-0 h-6 bg-gray-800 text-white text-xs flex items-center justify-center">
    Timeline (scroll to see full width)
  </div>
</div>
<div class="mt-2 flex gap-2">
  <ef-controls target="vertical-demo">
    <ef-toggle-play class="px-3 py-1 bg-blue-600 text-white rounded"></ef-toggle-play>
  </ef-controls>
</div>

Frame Snapping

When fps is set, scrubbing snaps to frame boundaries.

<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black" id="snap-demo" fps="30">
  <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" class="size-full object-contain"></ef-video>
</ef-timegroup>
<div class="flex flex-col gap-2 p-4 bg-gray-900 rounded-lg mt-4">
  <div class="text-white text-sm mb-2">Scrubbing snaps to 30fps frame boundaries:</div>
  <ef-scrubber target="snap-demo" fps="30"></ef-scrubber>
  <ef-controls target="snap-demo" class="flex gap-2 items-center">
    <ef-toggle-play class="px-3 py-1 bg-blue-600 text-white rounded"></ef-toggle-play>
    <ef-time-display class="text-white text-sm"></ef-time-display>
  </ef-controls>
</div>

Custom Styling

CSS Parts

Style scrubber appearance using ::part() selectors.

<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black" id="styled-scrubber">
  <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" class="size-full object-contain"></ef-video>
</ef-timegroup>
<div class="flex flex-col gap-2 p-4 bg-gray-900 rounded-lg mt-4">
  <ef-scrubber target="styled-scrubber" id="custom-scrubber"></ef-scrubber>
  <ef-controls target="styled-scrubber" class="flex gap-2 items-center">
    <ef-toggle-play class="px-3 py-1 bg-blue-600 text-white rounded"></ef-toggle-play>
    <ef-time-display class="text-white text-sm"></ef-time-display>
  </ef-controls>
</div>

<style>
  #custom-scrubber::part(scrubber) {
    background: linear-gradient(to right, #1e293b, #334155);
    height: 8px;
    border-radius: 4px;
  }

  #custom-scrubber::part(progress) {
    background: linear-gradient(to right, #3b82f6, #8b5cf6);
    border-radius: 4px;
  }

  #custom-scrubber::part(handle) {
    width: 16px;
    height: 16px;
    background: white;
    box-shadow: 0 2px 4px rgba(0,0,0,0.3);
  }
</style>

CSS Custom Properties

Control scrubber appearance through CSS variables:

ef-scrubber {
  --ef-scrubber-height: 4px;
  --ef-scrubber-background: rgba(255, 255, 255, 0.2);
  --ef-scrubber-progress-color: #fff;
  --ef-scrubber-handle-size: 12px;
}

Seek Events

<ef-scrubber target="my-video" id="my-scrubber"></ef-scrubber>

<script>
  const scrubber = document.getElementById('my-scrubber');
  scrubber.addEventListener('seek', (e) => {
    console.log('Seeking to:', e.detail, 'ms');
  });
</script>

Usage Modes

Horizontal mode — Compact progress bar for playback controls:

• Shows progress fill and draggable handle
• Best for control panels and compact UIs
• Automatically reads duration from context

Vertical mode — Timeline scrubber for editing:

• Shows vertical playhead line

• Requires zoom-scale for proper positioning

• Used internally by ef-timeline and ef-filmstrip

• Supports scrollable timelines with edge detection

Interaction

The scrubber supports:

• Click: Jump to position
• Drag: Scrub through timeline
• Touch: Mobile-friendly touch controls

All interactions automatically update the connected timeline's playback position.

Accessibility

The scrubber is keyboard accessible and supports:

• Click to seek
• Drag to scrub
• Touch gestures on mobile devices

For enhanced accessibility, consider wrapping in a labeled container:

<div role="group" aria-label="Video scrubber">
  <ef-scrubber target="my-video"></ef-scrubber>
</div>