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

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.

2. Prepare previews​

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.