React Video Editor

The Timeline component accepts the following props to customize its behavior and appearance:

Data Props

Prop	Type	Default Value	Description
`tracks`	`TimelineTrack[]`	required	Array of timeline tracks containing items to display
`totalDuration`	`number`	required	Total duration of the timeline in seconds
`currentFrame`	`number`	`undefined`	Current playhead position frame number
`fps`	`number`	`30`	Frames per second for timeline calculations

Event Handler Props

Prop	Type	Default Value	Description
`onFrameChange`	`(frame: number) => void`	`undefined`	Callback when playhead position changes
`onItemMove`	`(itemId: string, newStart: number, newEnd: number, newTrackId: string) => void`	`undefined`	Callback when an item is moved to a new position or track
`onItemResize`	`(itemId: string, newStart: number, newEnd: number) => void`	`undefined`	Callback when an item is resized
`onItemSelect`	`(itemId: string) => void`	`undefined`	Callback when an item is selected
`onDeleteItems`	`(itemIds: string[]) => void`	`undefined`	Callback when items are deleted
`onDuplicateItems`	`(itemIds: string[]) => void`	`undefined`	Callback when items are duplicated
`onSplitItems`	`(itemId: string, splitTime: number) => void`	`undefined`	Callback when an item is split at a specific time
`onTracksChange`	`(tracks: TimelineTrack[]) => void`	`undefined`	Callback when tracks are modified
`onAddNewItem`	`(item: Partial<TimelineItem> & { trackId: string; start: number; end: number }) => void`	`undefined`	Callback when a new item is added

Selection Props

Prop	Type	Default Value	Description
`selectedItemIds`	`string[]`	`undefined`	Array of currently selected item IDs
`onSelectedItemsChange`	`(itemIds: string[]) => void`	`undefined`	Callback when selection changes

UI Control Props

Prop	Type	Default Value	Description
`showZoomControls`	`boolean`	`false`	Whether to show zoom in/out controls
`showPlaybackControls`	`boolean`	`false`	Whether to show play/pause controls
`showTimelineGuidelines`	`boolean`	`true`	Whether to show alignment guidelines during drag
`showUndoRedoControls`	`boolean`	`false`	Whether to show undo/redo buttons
`showAspectRatioControls`	`boolean`	`false`	Whether to show aspect ratio controls

Playback Props

Prop	Type	Default Value	Description
`isPlaying`	`boolean`	`undefined`	Current playback state
`onPlay`	`() => void`	`undefined`	Callback when play is triggered
`onPause`	`() => void`	`undefined`	Callback when pause is triggered
`playbackRate`	`number`	`1`	Current playback speed multiplier
`setPlaybackRate`	`(rate: number) => void`	`undefined`	Callback to change playback rate

Track Management Props

Prop	Type	Default Value	Description
`autoRemoveEmptyTracks`	`boolean`	`true`	Whether to automatically remove empty tracks
`onAutoRemoveEmptyTracksChange`	`(enabled: boolean) => void`	`undefined`	Callback when auto-remove setting changes
`enableTrackDrag`	`boolean`	`true`	Whether tracks can be reordered by dragging
`enableMagneticTrack`	`boolean`	`true`	Whether items snap to track boundaries
`enableTrackDelete`	`boolean`	`true`	Whether tracks can be deleted

Behavior Props

Prop	Type	Default Value	Description
`hideItemsOnDrag`	`boolean`	`true` (desktop), `false` (mobile)	Whether to hide items during drag operations

Undo/Redo Props (External)

Prop	Type	Default Value	Description
`canUndo`	`boolean`	`undefined`	Whether undo operation is available
`canRedo`	`boolean`	`undefined`	Whether redo operation is available
`onUndo`	`() => void`	`undefined`	Callback to trigger undo
`onRedo`	`() => void`	`undefined`	Callback to trigger redo

Aspect Ratio Props

Prop	Type	Default Value	Description
`aspectRatio`	`AspectRatio`	`undefined`	Current aspect ratio setting
`onAspectRatioChange`	`(ratio: AspectRatio) => void`	`undefined`	Callback when aspect ratio changes

Prop Usage Examples

Essential Props

The minimum required props to get the timeline working:

<Timeline
  tracks={tracks}
  totalDuration={60}
  onTracksChange={setTracks}
/>

With Playback Control

Adding playback functionality:

<Timeline
  tracks={tracks}
  totalDuration={60}
  currentFrame={currentFrame}
  fps={30}
  isPlaying={isPlaying}
  onFrameChange={setCurrentFrame}
  onPlay={() => setIsPlaying(true)}
  onPause={() => setIsPlaying(false)}
  showPlaybackControls={true}
/>

With Selection Management

Handling item selection:

<Timeline
  tracks={tracks}
  totalDuration={60}
  selectedItemIds={selectedItems}
  onSelectedItemsChange={setSelectedItems}
  onItemSelect={(itemId) => console.log('Selected:', itemId)}
/>

With Full Event Handling

Complete event handler setup:

<Timeline
  tracks={tracks}
  totalDuration={60}
  onItemMove={handleItemMove}
  onItemResize={handleItemResize}
  onDeleteItems={handleDeleteItems}
  onDuplicateItems={handleDuplicateItems}
  onSplitItems={handleSplitItems}
  onAddNewItem={handleAddNewItem}
/>

With UI Controls

Enabling various UI features:

<Timeline
  tracks={tracks}
  totalDuration={60}
  showZoomControls={true}
  showPlaybackControls={true}
  showTimelineGuidelines={true}
  showUndoRedoControls={true}
  showAspectRatioControls={true}
/>

With Track Management

Configuring track behavior:

<Timeline
  tracks={tracks}
  totalDuration={60}
  enableTrackDrag={true}
  enableMagneticTrack={true}
  enableTrackDelete={true}
  autoRemoveEmptyTracks={false}
  onAutoRemoveEmptyTracksChange={setAutoRemoveEmptyTracks}
/>

With External Undo/Redo

Integrating with external undo/redo system:

<Timeline
  tracks={tracks}
  totalDuration={60}
  canUndo={historyManager.canUndo}
  canRedo={historyManager.canRedo}
  onUndo={historyManager.undo}
  onRedo={historyManager.redo}
  showUndoRedoControls={true}
/>

Type Definitions

`TimelineTrack`

interface TimelineTrack {
  id: string;
  name?: string;
  items: TimelineItem[];
  magnetic?: boolean;
  visible?: boolean;
  muted?: boolean;
}

`TimelineItem`

interface TimelineItem {
  id: string;
  trackId: string;
  start: number; // in seconds
  end: number;   // in seconds
  label?: string;
  type?: TrackItemType | string;
  color?: string;
  data?: any;
  // Media offset properties for split clips
  mediaStart?: number;
  mediaEnd?: number;
  mediaSrcDuration?: number;
}

`AspectRatio`

type AspectRatio = '16:9' | '9:16' | '1:1' | '4:3' | '3:4' | 'custom';

Props