Tracks and items

The EditorState data model — tracks, items, item types, and enter and exit animations

The editor keeps a project as one EditorState object. The state holds a list of tracks. Each track holds a list of items. An item is one clip on the timeline, for example a video, a text, or a shape.

EditorState
└── tracks: Track[]
    └── items: Item[]

All types on this page come from @reactvideoeditor/react-video-editor/types.

import {
  ItemType,
  type EditorState,
  type Track,
  type Item,
  type TextItem,
} from '@reactvideoeditor/react-video-editor/types';

EditorState

Field	Type	Description
`tracks`	`Track[]`	The tracks of the project, from the top track to the bottom track.
`dimensions`	`{ width: number; height: number }`	Optional. The composition size. If you do not set it, the editor uses 16:9 at 1280×720.
`aspectRatio`	`AspectRatio`	Deprecated. Use `dimensions`. The editor reads it only when `dimensions` is not set.
`backgroundColor`	`string`	Deprecated. Use `background`.
`background`	`CanvasBackground`	Optional. The background of the composition. It is not a timeline item.
`playbackRate`	`number`	The playback speed.
`savedAt`	`number`	Optional. A Unix time in milliseconds. The editor sets it on each save.

Track

Field	Type	Description
`id`	`string`	A unique ID.
`name`	`string`	Optional. The track name.
`items`	`Item[]`	The items on the track.
`magnetic`	`boolean`	If `true`, the track closes the gaps between items.
`muted`	`boolean`	If `true`, the track plays no sound.
`visible`	`boolean`	If `false`, the track does not show.

The track order is the layer order. Track 0 shows in front of all other tracks.

Item types

The ItemType enum gives the type of each item:

Enum value	String	Item interface
`ItemType.VIDEO`	`'video'`	`VideoItem` (and `CameraVideoItem`)
`ItemType.IMAGE`	`'image'`	`ImageItem`
`ItemType.TEXT`	`'text'`	`TextItem`
`ItemType.AUDIO`	`'audio'`	`AudioItem`
`ItemType.CAPTION`	`'caption'`	`CaptionItem`
`ItemType.SHAPE`	`'shape'`	`ShapeItem`
`ItemType.ZOOM`	`'zoom'`	`ZoomItem`
`ItemType.LOTTIE`	`'lottie'`	`LottieItem`

Item is the union of all item interfaces.

Stickers were removed

The sticker item type was removed. You can still open a saved project that has sticker items. When the editor loads the project, it removes the sticker items. If a track holds only sticker items, the editor also removes that track.

Common fields (BaseItem)

All items have these fields:

Field	Type	Description
`id`	`string`	A unique ID (UUID).
`type`	`ItemType`	The item type.
`from`	`number`	The start frame on the timeline.
`durationInFrames`	`number`	The length of the item, in frames.
`left`	`number`	The X position on the canvas, in px.
`top`	`number`	The Y position on the canvas, in px.
`width`	`number`	The width, in px.
`height`	`number`	The height, in px.
`rotation`	`number`	The rotation, in degrees.
`originX`	`number`	Optional. The X point that keyframed scale, stretch, and rotation turn around, in % of the item box. Default: `50`.
`originY`	`number`	Optional. The Y point for the same purpose. Default: `50`.
`keyframes`	`ItemKeyframes`	Optional. The animated properties of the item. See Keyframes.

Most items also have a styles object. All styles objects accept these base fields:

Field	Type	Description
`opacity`	`number`	From 0 to 1.
`zIndex`	`number`	Optional layer index.
`transform`	`string`	A CSS transform.
`shadow`	`number`	Shadow strength, from 0 (off) to 100.

Item fields by type

The tables below show the important fields of each item type. Read the type definitions in your IDE for the full list.

VideoItem

Field	Type	Description
`src`	`string`	The video URL.
`content`	`string`	The thumbnail URL.
`mediaStartTime`	`number`	The start point in the source, in seconds.
`mediaSrcDuration`	`number`	The full length of the source, in seconds.
`speed`	`number`	The playback speed.
`freezeFrame`	`boolean`	If `true`, the item holds the source frame at `mediaStartTime` for the full item length. The item plays no sound.
`previewThumbnails`	`PreviewThumbnails`	Timeline thumbnail files. If you set them, the editor does not download the video to make thumbnails.
`transcript`	`Transcript`	The transcript of the audio. Captions and other transcript tools use it.
`styles.volume`	`number`	The volume. `0` mutes the item.
`styles.objectFit`	`'contain' \| 'cover' \| 'fill' \| 'none' \| 'scale-down'`	How the video fills the item box.
`styles.borderRadius`	`string`	The corner radius, for example `'12px'`.
`styles.animation`	`AnimationConfig`	The enter and exit animations. See Animations.
`styles.cropEnabled`, `cropX`, `cropY`, `cropWidth`, `cropHeight`	`boolean`, `number`	The crop settings.

CameraVideoItem

A CameraVideoItem is a VideoItem with mediaRole: 'camera'. Its type is ItemType.VIDEO. The editor gives recorded camera clips a special panel, but it renders them as normal video. The optional camera object holds the camera shape ('square' | 'horizontal' | 'vertical' | 'original'), the shadow, the zoom, and the layout preset.

AudioItem

Field	Type	Description
`src`	`string`	The audio URL.
`content`	`string`	The label on the timeline.
`mediaStartTime`	`number`	The start point in the source, in seconds.
`mediaSrcDuration`	`number`	The full length of the source, in seconds.
`sourceVideoId`	`string`	The ID of the video that the audio came from, if you detached it.
`styles.volume`	`number`	The volume.
`styles.fadeIn`	`number`	The fade-in length.
`styles.fadeOut`	`number`	The fade-out length.

TextItem

Field	Type	Description
`content`	`string`	The text.
`counter`	`TextCounter`	Optional. If set, the item shows a counting number in place of `content`. See Count number.
`styles.fontSize`	`string`	Required. For example `'4rem'`.
`styles.fontWeight`	`string`	Required.
`styles.color`	`string`	Required.
`styles.backgroundColor`	`string`	Required.
`styles.fontFamily`	`string`	Required.
`styles.fontStyle`	`string`	Required.
`styles.textDecoration`	`string`	Required.
`styles.textAlign`	`'left' \| 'center' \| 'right'`	The alignment.
`styles.lineHeight`, `styles.letterSpacing`	`string`	Line and letter spacing.
`styles.textShadow`	`string`	A CSS text shadow.
`styles.textStrokeWidth`	`number`	The outline width, in px. The editor paints the outline under the fill. `0` or no value shows no outline.
`styles.textStrokeColor`	`string`	The outline colour.
`styles.animation`	`AnimationConfig`	The enter and exit animations.

ImageItem

Field	Type	Description
`src`	`string`	The image URL.
`content`	`string`	Optional. The thumbnail URL.
`styles.objectFit`	`'contain' \| 'cover' \| 'fill' \| 'none' \| 'scale-down'`	How the image fills the item box.
`styles.borderRadius`	`string`	The corner radius.
`styles.filter`	`string`	A CSS filter.
`styles.animation`	`AnimationConfig`	The enter and exit animations.
`styles.cropEnabled`, `cropX`, `cropY`, `cropWidth`, `cropHeight`	`boolean`, `number`	The crop settings.

CaptionItem

Field	Type	Description
`captions`	`Caption[]`	The caption lines and their word timings.
`template`	`string`	Optional. The ID of the caption style template.
`styles`	`CaptionStyles`	Optional. The caption styles.
`sourceVideoId`	`string`	The ID of the video that the captions came from. The editor uses it to keep the captions in sync.

See Setup Captions for the caption styles.

ShapeItem

Field	Type	Description
`content`	`string`	The label on the timeline.
`shape`	`ShapeKind`	`'rectangle' \| 'ellipse' \| 'arc' \| 'line' \| 'particles' \| 'paper'`. If you do not set it, the item is a rectangle.
`styles.fill`	`string`	The fill colour.
`styles.gradient`	`string \| ShapeGradient`	A linear or radial gradient. It replaces the fill.
`styles.stroke`, `styles.strokeWidth`	`string`, `number`	The outline.
`styles.borderRadius`	`string`	The corner radius of a rectangle.
`styles.softEdge`	`number`	The blur of the edge, in px.
`styles.dropShadow`	`ShapeShadow`	A drop shadow.
`styles.arc`, `line`, `particles`, `paper`	objects	The settings of each shape kind.
`styles.draw`	`number`	The drawn part of an arc or a line, from 0 to 100.

See Shapes for all shape settings.

LottieItem

Field	Type	Description
`src`	`string`	The URL of the Lottie JSON file.
`content`	`string`	The label on the timeline.
`loop`	`boolean`	Optional. Default: `true`.
`speed`	`number`	Optional. From 0.5 to 2. Default: `1`.
`styles.opacity`	`number`	The opacity.
`styles.animation`	`AnimationConfig`	The enter and exit animations.

ZoomItem

A zoom item does not show as a layer. It zooms the canvas while it plays.

Field	Type	Description
`content`	`string`	The label on the timeline, for example `'Zoom In'`.
`styles.zoomType`	`'in' \| 'out' \| 'in-out' \| 'shake' \| 'follow'`	The zoom type. `'follow'` follows the recorded pointer of a video item.
`styles.zoomLevel`	`number`	The scale, for example `1.5` for 150%.
`styles.targetX`, `styles.targetY`	`number`	The zoom centre, in %. Default: `50`.
`styles.easing`	`'linear' \| 'ease-in' \| 'ease-out' \| 'ease-in-out'`	The ease of the zoom.
`styles.followPointerItemId`	`string`	Required when `zoomType` is `'follow'`. The ID of the video item with pointer data.

Animations

Video, image, text, shape, and Lottie items have styles.animation. This object holds one enter animation and one exit animation.

interface AnimationConfig {
  enter?: string;          // The key of an enter animation, for example 'fade'
  exit?: string;           // The key of an exit animation
  enterTiming?: AnimationTiming;
  exitTiming?: AnimationTiming;
}

interface AnimationTiming {
  duration?: number;       // The length, in seconds
  delay?: number;          // The wait, in seconds
  ease?: AnimationEaseName;
}

type AnimationEaseName =
  | 'linear' | 'smooth' | 'out' | 'whip'
  | 'glide' | 'breathe' | 'back' | 'spring';

An enter animation starts after delay from the item start.
An exit animation ends delay before the item end.
If you do not set a timing field, the animation uses its default timing.
In the editor, the Animate tab of each item panel sets the animations. The Advanced controls set the duration (0.1 to 3 seconds), the delay, and the ease.

For more complex motion, use keyframes.

Example

import { ItemType, type EditorState } from '@reactvideoeditor/react-video-editor/types';

const editorState: EditorState = {
  dimensions: { width: 1920, height: 1080 },
  playbackRate: 1,
  tracks: [
    {
      id: 'track-1',
      magnetic: false,
      muted: false,
      visible: true,
      items: [
        {
          id: 'title-1',
          type: ItemType.TEXT,
          from: 0,
          durationInFrames: 90,
          left: 660,
          top: 450,
          width: 600,
          height: 180,
          rotation: 0,
          content: 'Hello',
          styles: {
            fontSize: '4rem',
            fontWeight: '700',
            color: '#ffffff',
            backgroundColor: 'transparent',
            fontFamily: 'Inter',
            fontStyle: 'normal',
            textDecoration: 'none',
            textAlign: 'center',
            animation: {
              enter: 'fade',
              enterTiming: { duration: 0.5, ease: 'out' },
            },
          },
        },
      ],
    },
  ],
};

Tracks and items

On this page