Skip to main content

createElementPayload()v4.0.502

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

Example​

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

const elementSourceCode = `
import {Img} from 'remotion';

export const MyElement = ({logoSrc}: {logoSrc: string}) => {
  return <Img name="Logo" src={logoSrc} />;
};
`;

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,
  initialProps: {logoSrc: staticFileRef('my-element/logo.png')},
  assets: [
    {
      path: 'my-element/logo.png',
      type: 'url',
      url: 'https://example.com/logo.png',
    },
    {
      path: 'my-element/data.json',
      type: 'base64',
      data: 'eyJvayI6dHJ1ZX0=',
    },
  ],
});

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 an Element 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.

assets?v4.0.528​

Files to install in the project's public directory. The default is [].

Set path to a forward-slash path relative to the public directory. Use staticFileRef() in initialProps to pass the installed asset to your component. Studio generates a staticFile() expression on the component invocation and leaves the Element source unchanged. Paths cannot be absolute, contain traversal or platform-unsafe segments, or conflict with another declared asset path.

For a remote file, set type to 'url' and provide an HTTP(S) url without credentials. For an embedded file, set type to 'base64' and provide strictly encoded data. Browser Studio requires remote servers to allow cross-origin requests (CORS).

An installation can contain at most 100 assets and 50MB of downloaded or decoded data in total. The complete Element payload remains limited to 250,000 JSON characters, including embedded base64 data. Use remote URLs for larger files.

Studio fetches assets only after you confirm the installation. An existing file is reused when its bytes match. Different contents cause the installation to fail, even when you approve replacing an existing Element source file. Undo removes installed source changes but retains successfully installed assets; redo does not download them again.

Assets use Element payload version 2. Asset-free payloads continue to use version 1. A Studio that only supports version 1 asks you to upgrade instead of installing source without its assets.

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​

Props to write onto the installed component invocation, in both installation modes. The default is null. In 'wrapped' mode, the component invocation is inside the generated Sequence.

Use JSON-compatible values and valid JSX attribute names. Asset props can use staticFileRef(), including inside nested objects and arrays. Studio turns these references into staticFile() expressions on the caller, not inside the Element source.

For component-owned-sequence, omit from, durationInFrames, and name because Studio supplies them. In this mode, style must be an object.

Pass the corresponding values to the component preview, using hosted URLs instead of asset references. Element dimensions are not passed as component props in component-owned-sequence mode, so include width and height when the component needs them.

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. Asset-free payloads use version 1; payloads with assets use version 2. 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​