Skip to main content

addElement()v4.0.530

Inserts an element created with createElement() into a composition component or relative to an existing node, and adds the imports it needs.

warning

Draft API: This API is experimental and may change.

add-element.ts
import {addElement, createElement, type CodemodProject} from '@remotion/codemods';

declare const project: CodemodProject;

const result = addElement({
  project,
  element: createElement({
    component: 'Solid',
    importPath: 'remotion',
    props: {width: 1920, height: 1080, color: 'gray'},
  }),
  target: {
    type: 'composition',
    compositionFile: 'src/Root.tsx',
    compositionId: 'MyComposition',
  },
});

console.log(result.changes);
console.log(result.insertedNode);

To place the element on the timeline, wrap it in a <Sequence>:

add-timed-element.ts
import {addElement, createElement, type CodemodProject} from '@remotion/codemods';

declare const project: CodemodProject;

const video = createElement({
  component: 'Video',
  importPath: '@remotion/media',
  props: {src: 'https://example.com/video.mp4'},
});

const result = addElement({
  project,
  element: createElement({
    component: 'Sequence',
    importPath: 'remotion',
    props: {from: 30, durationInFrames: 90},
    children: [video],
  }),
  target: {
    type: 'composition',
    compositionFile: 'src/Root.tsx',
    compositionId: 'MyComposition',
  },
});

Media files are not copied or downloaded, metadata is not probed, and packages are not installed. The project must already contain the dependencies needed by the generated imports.

Options​

project​

An in-memory CodemodProject. The input project is not mutated.

element​

The element to insert, created with createElement().

target​

Where to insert the element. One of the following objects.

{type: 'composition', compositionFile, compositionId}​

Appends the element to the component of the composition with the static ID compositionId, registered in compositionFile. The component may be imported from another project file. If the component returns a single element, both are grouped in a fragment. If it returns null, the element becomes its content.

{type: 'component', filePath, exportName}​

Appends the element to the root returned by the component that filePath exports as exportName, or as its default export when exportName is 'default'. Use it when the component is already known, for example from resolveCompositionComponent(). Follows the same rules as the composition target.

{type: 'inside', node}​

Appends the element as the last child of node. Self-closing elements are expanded.

{type: 'before', node}​

Inserts the element before node. If the node has no parent element, for example because it is returned directly, both are grouped in a fragment.

{type: 'after', node}​

Inserts the element after node, following the same rules as before.

Obtain a node from getNodes() or a previous result. See node references.

prettierConfigOverride?​

Formatting options for generated source, such as singleQuote, useTabs, tabWidth, printWidth, and bracketSpacing. Defaults to null, which follows the existing source style.

Return value​

An object with the following properties.

changes​

An array of {filePath, previousContents, nextContents} file changes.

nodePathRemappings​

An array of {filePath, oldNodePath, newNodePath} mappings. A null old path indicates an insertion; a null new path indicates removal. Every inserted element, including children of the inserted element, is listed with a null old path. See node references.

insertedNode​

The reference of the outermost inserted element. Use getNodes() and its parentNodePath to find inserted children.

Errors​

Throws when the target cannot be resolved, the composition component cannot receive content, or the element is invalid. Failed edits leave the input project unchanged.

Compatibility​

BrowsersServersEnvironments
Chrome
Firefox
Safari
Node.js
Bun
Serverless Functions

See also​