Installation & Setup
Install @keplar-404/react-timeline-editor and @keplar-404/timeline-engine and render your first timeline in minutes.
Install the Packages
Both packages are required. The react-timeline-editor provides the React component,
while timeline-engine provides the standalone playback logic they both share.
npm install @keplar-404/react-timeline-editor @keplar-404/timeline-enginebun add @keplar-404/react-timeline-editor @keplar-404/timeline-enginepnpm add @keplar-404/react-timeline-editor @keplar-404/timeline-engineyarn add @keplar-404/react-timeline-editor @keplar-404/timeline-engineImport the CSS Stylesheet
The timeline component requires its stylesheet to render correctly. Import it once — either in your global CSS file or directly in your component.
Add this to your global.css (or equivalent entry stylesheet):
@import '@keplar-404/react-timeline-editor/dist/react-timeline-editor.css';Import it at the top of any file that renders <Timeline />:
import '@keplar-404/react-timeline-editor/dist/react-timeline-editor.css';Skipping this import will result in an unstyled, broken-looking timeline.
Render Your First Timeline
The <Timeline /> component requires two props: editorData (your track data) and effects (the effect definitions).
import React, { useState } from 'react';
import { Timeline, TimelineRow, TimelineEffect } from '@keplar-404/react-timeline-editor';
import '@keplar-404/react-timeline-editor/dist/react-timeline-editor.css';
const mockData: TimelineRow[] = [
{
id: 'track-1',
actions: [
{
id: 'action-1',
start: 0, // Start time in seconds
end: 2, // End time in seconds
effectId: 'effect-0',
},
],
},
];
const mockEffect: Record<string, TimelineEffect> = {
'effect-0': {
id: 'effect-0',
name: 'Example Effect',
},
};
export const TimelineEditor = () => {
const [data, setData] = useState<TimelineRow[]>(mockData);
return (
<div style={{ width: "100%", height: "400px" }}>
<Timeline
editorData={data}
effects={mockEffect}
onChange={(newData) => setData(newData)}
style={{ width: "100%", height: "100%" }}
/>
</div>
);
};The <Timeline /> is a controlled component. You manage the data in state, and pass
updates back via the onChange callback. The timeline will call onChange whenever the
user drags or resizes an action block.
(Optional) Enable Auto-Scroll
If users drag action blocks near the timeline edge, you can enable automatic panning:
<div style={{ width: "100%", height: "400px" }}>
<Timeline
editorData={data}
effects={mockEffect}
onChange={setData}
autoScroll={true} // Scroll the timeline when dragging near edges
style={{ width: "100%", height: "100%" }}
/>
</div>Attribution: This package is built on top of and derived from @xzdarcy/react-timeline-editor. Full credit for the original fundamental engine and architecture goes to @xzdarcy. This fork by @keplar-404 introduces major custom capabilities.