Skip to main content

createElementPayload()v4.0.502

Creates a validated, versioned Element payload for setStudioDragData() and installInStudio().

Example​

element-payload.ts
import {createElementPayload} from '@remotion/studio-protocol';

const elementSourceCode = `
export const MyElement = () => {
  return <div>Hello world</div>;
};
`;

const payload = createElementPayload({
  displayName: 'My Element',
  slug: 'my-element',
  sourceCode: elementSourceCode,
  dependencies: [
    {name: '@remotion/google-fonts', version: null},
    {name: 'color-namer', version: '1.4.0'},
  ],
  dimensions: {width: 900, height: 260},
  durationInFrames: 90,
});

Arguments​

Pass an object with the following properties.

displayName​

The name shown in the Studio confirmation dialog. It must be a non-empty string shorter than 120 characters.

slug​

A lowercase Element identifier. Its final path segment is used to create the .element.tsx filename. Directory traversal and unsafe filename characters are rejected.

sourceCode​

A string containing the complete Element source code. It must contain exactly one exported named component.

See Integrating a component library with Studio for recommended ways to preview a component and represent it as Element source in Vite-based projects and Next.js.

dependencies​

An array of npm packages needed by the Element. Declare each dependency as an object with name and version properties. Duplicate names are removed.

For @remotion/* packages, set version to null. Studio installs the version matching the Remotion project. Every non-Remotion package must specify an exact semantic version. Version ranges and tags are not accepted.

Do not declare react, react-dom, or remotion; every Remotion project already provides them.

dimensions​

The preferred width and height, or null for an Element without fixed dimensions. Both values must be positive finite numbers.

Studio uses these dimensions for the drag preview, drop position, and the generated <Sequence> when installationMode is 'wrapped'. They are not passed to the component as width and height props when installationMode is 'component-owned-sequence'.

durationInFrames​

The preferred duration shown while dragging. It must be a positive integer.

initialProps?v4.0.524​

Use initialProps when a component-owned-sequence Element needs replaceable starter content. Studio writes each property onto the installed component. The default is null.

Use JSON-compatible values and valid JSX attribute names. For component-owned-sequence, omit from, durationInFrames, and name because Studio supplies them. In this mode, style must be an object.

Pass the same props to the component preview. Element dimensions are not passed as component props, so include width and height when the component needs them.

In 'wrapped' mode, Studio also passes initialProps to the component inside the generated Sequence. Most wrapped Elements do not need this because their editable values can stay on internal Interactive call sites in the copied source.

installationMode?v4.0.506​

Controls how Studio installs the Element. The default is 'wrapped'.

With 'wrapped', Studio generates a <Sequence> around the component to provide its timing, name, dimensions, and position.

With 'component-owned-sequence', Studio puts timing, name, and absolute positioning props on the component call without adding an outer Sequence. The component must provide its own Studio-editable Sequence and rendered dimensions.

See Design it for composition for guidance on choosing a mode and wiring the component.

Return value​

A StudioElementPayload with payload version 1. Pass the returned object unchanged to a transport API instead of serializing it manually.

Invalid input throws a TypeError.

Compatibility​

BrowsersEnvironments
Chrome
Firefox
Safari

See also​