Evo Timeline Editor

Evo Timeline Editor is a React-based component designed for building animation timelines, video editors, or other time-based editors with ease.

This package is a maintained and improved fork of @xzdarcy/react-timeline-editor, with added support for React 18+ and React 19.

✨ Features

• 🛠 Drag & resize with easy-to-use control hooks
• 🔗 Grid snapping and guideline snapping supported
• 🍿 Automatically calculates action length with infinite scroll
• 🎨 Fully customizable styles
• 🛁 Decoupled timeline engine for playback control

🚀 Getting Started

npm install evo-timeline-editor-react

import React from "react";
import { Timeline } from "evo-timeline-editor-react";

export const TimelineEditor = () => {
  return (
    <Timeline
      editorData={[]}
      effects={{}}
    />
  );
};

⚙️ Props

| Prop | Description | Type | Default | |-------------------------|-----------------------------------------------------------------------------|---------------------------------------------------------------------------------------|-------------| | style | Custom CSS for outer timeline container | React.CSSProperties | -- | | editorData | Timeline track data (required) | TimelineRow[] | required | | effects | Map of timeline effects (required) | Record<string, TimelineEffect> | required | | scrollTop | ScrollTop position (deprecated, use ref.setScrollTop) | number | -- | | onScroll | Triggered when timeline scrolls | (params: OnScrollParams) => void | -- | | autoScroll | Enables auto-scroll while dragging | boolean | false | | autoReRender | Auto re-render timeline on data or time change | boolean | true | | onChange | Triggered when timeline data changes | (editorData: TimelineRow[]) => boolean | void | -- | | scale | Logical scale unit (e.g. 1 second per block) | number (>0) | 1 | | scaleWidth | Width of each scale unit in pixels | number (>0) | 160 | | minScaleCount | Minimum number of scale blocks | number (>= 1) | 20 | | maxScaleCount | Maximum number of scale blocks | number (>= minScaleCount) | Infinity | | scaleSplitCount | Subdivisions per scale | number (>0) | 10 | | startLeft | Distance from left to start of timeline | number (>= 0) | 20 | | rowHeight | Height per timeline row (in px) | number (> 0) | 32 | | gridSnap | Enable grid snapping | boolean | false | | dragLine | Enable guideline snapping | boolean | false | | hideCursor | Hide the playhead cursor | boolean | false | | disableDrag | Disable all drag functionality | boolean | false | | engine | Custom timeline engine | ITimelineEngine | built-in | | ref | Access to timeline engine via TimelineState | Ref<TimelineState> | -- |

🔧 Advanced Callbacks

You can customize almost every interaction on the timeline:

• getActionRender(action, row): custom action rendering
• getScaleRender(scale): custom scale unit rendering
• onActionMoveStart, onActionMoving, onActionMoveEnd
• onActionResizeStart, onActionResizing, onActionResizeEnd
• onClickRow, onClickAction, onClickActionOnly
• onDoubleClickRow, onDoubleClickAction
• onContextMenuRow, onContextMenuAction
• onCursorDragStart, onCursorDrag, onCursorDragEnd
• onClickTimeArea
• getAssistDragLineActionIds

🧠 Types Included

You can import types like TimelineRow, TimelineAction, TimelineEffect, and TimelineState for full TypeScript support.

✅ React 19 Support

This package is fully compatible with React 18 and React 19.

🧹 Want to Contribute?

Feel free to open issues, suggest improvements, or fork the repo!

License

MIT