evo-timeline-editor-react
Version:
[](https://www.npmjs.com/package/evo-timeline-editor-react)
108 lines (77 loc) • 6.84 kB
Markdown
# Evo Timeline Editor
[](https://www.npmjs.com/package/evo-timeline-editor-react)
**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`](https://www.npmjs.com/package/@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
```bash
npm install evo-timeline-editor-react
```
```tsx
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