Data Interface Reference

Complete TypeScript reference for TimelineRow, TimelineAction, and TimelineEffect.

TimelineRow

export interface TimelineRow {
  id: string;
  actions: TimelineAction[];
  classNames?: string[];
  selected?: boolean;
  rowHeight?: number;
}

Property	Type	Required	Description
`id`	`string`	✅	Unique row identifier
`actions`	`TimelineAction[]`	✅	List of action blocks in this row
`classNames`	`string[]`	—	Additional CSS classes for the row element
`selected`	`boolean`	—	Visual selected state
`rowHeight`	`number`	—	Override the global `rowHeight` for this row

TimelineAction

export interface TimelineAction {
  id: string;
  start: number;
  end: number;
  effectId: string;
  movable?: boolean;
  flexible?: boolean;
  disabled?: boolean;
  selected?: boolean;
  minStart?: number;
  maxEnd?: number;
  style?: React.CSSProperties;
  className?: string;
  data?: any;
}

Property	Type	Required	Default	Description
`id`	`string`	✅	—	Unique action identifier
`start`	`number`	✅	—	Start time in seconds
`end`	`number`	✅	—	End time in seconds
`effectId`	`string`	✅	—	ID of the effect that governs this action
`movable`	`boolean`	—	`true`	If `false`, cannot be dragged horizontally
`flexible`	`boolean`	—	`true`	If `false`, cannot be resized
`disabled`	`boolean`	—	`false`	Visual disabled state
`selected`	`boolean`	—	`false`	Visual selected state
`minStart`	`number`	—	—	Minimum allowed start time (clamps dragging)
`maxEnd`	`number`	—	—	Maximum allowed end time (clamps dragging)
`style`	`CSSProperties`	—	—	Inline style for the block element
`className`	`string`	—	—	Additional CSS class
`data`	`any`	—	—	Custom metadata payload

TimelineEffect

export interface TimelineEffect {
  id: string;
  name: string;
  source?: TimeLineEffectSource;
}

export interface TimeLineEffectSource {
  start?: (params: EffectSourceParams) => void;
  enter?: (params: EffectSourceParams) => void;
  update?: (params: EffectSourceParams) => void;
  leave?: (params: EffectSourceParams) => void;
  stop?: (params: EffectSourceParams) => void;
}

export interface EffectSourceParams {
  action: TimelineAction;
  row: TimelineRow;
  engine: TimelineEngine;
  isPlaying: boolean;
  time: number;
}

Callback	When it fires	Can return `false`?
`start`	Playback begins while cursor is inside the action	No
`enter`	Playhead crosses into the action	No
`update`	Every tick while inside the action	No
`leave`	Playhead crosses out of the action	No
`stop`	Playback is paused inside the action	No

Complete Example

import { TimelineRow, TimelineEffect } from "@keplar-404/react-timeline-editor";

// Extend TimelineAction for custom data
interface MyAction extends TimelineAction {
  data: {
    name: string;
    src: string;
  };
}

const effects: Record<string, TimelineEffect> = {
  audio: {
    id: "audio",
    name: "Play Audio",
    source: {
      enter: ({ action, time }) => {
        // Start playing audio at (time - action.start) offset
        console.log("Starting audio:", (action as MyAction).data.src);
      },
      leave: ({ action }) => {
        console.log("Stopping audio:", (action as MyAction).data.src);
      },
    },
  },
};

const editorData: TimelineRow[] = [
  {
    id: "audio-track",
    actions: [
      {
        id: "audio-clip-1",
        start: 0,
        end: 10,
        effectId: "audio",
        data: { name: "Background Music", src: "/audio/bg.mp3" },
      } as MyAction,
    ],
  },
];

Data Interface Reference

TimelineRow

TimelineAction

TimelineEffect

Complete Example

On this page