Skip to main content

Contributing an Element

Have a small, remixable Remotion Element? We'd like to see it. Before submitting, read the Element guidelines. They apply to Elements in the official gallery and third-party libraries alike.

1. Develop the Element​

  1. Copy packages/docs/elements-template to packages/docs/elements/<category>/<slug>. The template includes a component and an index.mdx documentation page.
  2. Add its metadata to packages/docs/src/components/Elements/element-definitions.ts to register its Studio composition, and add its page to packages/docs/elements-sidebars.ts.
  3. Build and preview the Element in Studio:
Terminal
cd packages/docs && bun remotion

The scaffold-element skill is an Agent Skill that can set up the template and Studio composition.

Declare the Element's dependencies in element-definitions.ts as described in the dependencies field.

If the Element needs starter props, put them in initial-props.ts, type them with satisfies ComponentProps<typeof YourComponent>, and register them as initialProps in element-definitions.ts.

For installed assets, declare assets in element-definitions.ts and put staticFileRef() references in installationProps. Keep preview URLs in initialProps. For Elements without installed assets, use assets: [] and installationProps: null. installationProps shallowly overrides initialProps only for installation; an overridden object or array replaces that entire prop.

2. Prepare previews​

Choose a poster frame that clearly shows the Element. The video preview should cover the Element's full duration and, when applicable, include its entrance and exit animations.

Render and visually review the Element and its previews:

Terminal
cd packages/docs
bun run render-element-previews --element=<category>/<slug>
bun test src/test/elements.test.ts

To make previews visible in the pull request deployment:

  1. Copy the rendered preview assets to packages/docs/static/elements and commit them.
  2. Set image, posterUrl, and videoUrl to /elements/<category>-<slug>-preview.png and /elements/<category>-<slug>-preview.mp4, matching those files.

3. Open the pull request​

Include:

  • The implementation, page, and gallery registration
  • What makes it useful
  • A working PNG and MP4 preview
  • Links to inspiration, if any

Keep “Allow edits from maintainers” enabled on the pull request. After approval, a repository maintainer uploads the gallery previews to static storage.