Transport Bar

Add a professional play/pause/seek/loop control UI to your timeline with useTimelinePlayer and TransportBar.

The TransportBar is a pre-built playback control UI designed to work seamlessly with useTimelinePlayer. It provides a professional-grade playback interface out of the box.

Live Preview

0:00.00TIME

SPEED

What It Includes

Transport controls: Return to start, Rewind, Play/Pause, Forward, Stop
Time display: Formatted M:SS.cs readout (customizable via formatDisplayTime)
Playback rate: Speed selector (0.25x, 0.5x, 1x, 2x, 4x - customizable via playRates)
Loop controls: Toggle and input fields for loop region

Basic Usage

import React, { useState, useRef } from "react";
import {
  Timeline,
  TimelineState,
  TransportBar,
  LoopZoneOverlay,
  useTimelinePlayer,
} from "@keplar-404/react-timeline-editor";

export const EditorWithTransport = () => {
  const timelineRef = useRef<TimelineState>(null);
  const [data, setData] = useState([]);
  const [scrollLeft, setScrollLeft] = useState(0);

  // 1. Initialize the player hook — it attaches engine listeners automatically
  const player = useTimelinePlayer(timelineRef);

  return (
    <div className="timeline-preview-container">
      {/* 2. Render the bar and pass the player object */}
      <div style={{ borderBottom: "1px solid #333", flexShrink: 0 }}>
        <TransportBar player={player} />
      </div>

      <div style={{ flex: 1, position: "relative" }}>
        <Timeline
          ref={timelineRef}
          editorData={data}
          effects={{}}
          autoScroll={true}
          onChange={setData}
          onScroll={(p) => setScrollLeft(p.scrollLeft)}
          style={{ width: "100%", height: "100%" }}
        />
        <LoopZoneOverlay scrollLeft={scrollLeft} loopStart={1} loopEnd={5} />
      </div>

      <style>{`
        .editor-container {
          background: #1a1a1a;
          border-radius: 8px;
          overflow: hidden;
          width: 100%;
          height: 400px;
          display: flex;
          flexDirection: "column";
        }
      `}</style>
    </div>
  );
};

With Loop Controls

Integrate a loop region by passing the loop configuration:

export const EditorWithLoopTransport = () => {
  const timelineRef = useRef<TimelineState>(null);
  const [data, setData] = useState([
    {
      id: "Track 1",
      actions: [{ id: "A", start: 0, end: 10, effectId: "effect0" }],
    },
  ]);
  const [loopOn, setLoopOn] = useState(false);
  const [loopStart, setLoopStart] = useState(1);
  const [loopEnd, setLoopEnd] = useState(5);
  const [scrollLeft, setScrollLeft] = useState(0);

  const player = useTimelinePlayer(timelineRef, {
    loop: { enabled: loopOn, start: loopStart, end: loopEnd },
  });

  return (
    <div className="timeline-preview-container">
      <div style={{ borderBottom: "1px solid #333", flexShrink: 0 }}>
        <TransportBar
          player={player}
          loop={{
            enabled: loopOn,
            start: loopStart,
            end: loopEnd,
            onToggle: () => setLoopOn(!loopOn),
            onStartChange: setLoopStart,
            onEndChange: setLoopEnd,
          }}
        />
      </div>
      <div style={{ flex: 1, position: "relative" }}>
        <Timeline
          ref={timelineRef}
          editorData={data}
          effects={{}}
          autoScroll={true}
          onScroll={(p) => setScrollLeft(p.scrollLeft)}
          style={{ width: "100%", height: "100%" }}
        />
        {loopOn && (
          <LoopZoneOverlay
            scrollLeft={scrollLeft}
            loopStart={loopStart}
            loopEnd={loopEnd}
            onLoopStartChange={setLoopStart}
            onLoopEndChange={setLoopEnd}
          />
        )}
      </div>
    </div>
  );
};

Using the Player API Directly

If you prefer to build your own UI, use useTimelinePlayer directly:

const player = useTimelinePlayer(timelineRef);

// player.isPlaying    → boolean
// player.currentTime  → number (seconds)
// player.playRate     → number (speed multiplier)
// player.play()       → start playback
// player.pause()      → pause
// player.stop()       → stop and reset to 0
// player.toStart()    → jump to time 0
// player.rewind()     → jump back by seekStep seconds (default 5s)
// player.forward()    → jump forward by seekStep seconds
// player.setTime(t)   → jump to a specific time
// player.setPlayRate(r) → change playback speed

See the Transport Bar API Reference for the full props and return types of both TransportBar and useTimelinePlayer.