Skip to main content

addElementLibraryToStudio()v4.0.518

Requests that a third-party Element Library is added to a recently focused Remotion Studio project.

Example​

add-element-library.ts
import {addElementLibraryToStudio} from '@remotion/studio-protocol';

const result = await addElementLibraryToStudio({
  url: 'https://example.com/elements',
  displayName: 'Acme Elements',
  captionStylesUrl: 'https://example.com/elements/captions',
});

if (!result.success) {
  console.error(result.code, result.message);
} else {
  console.log(result.status); // "awaiting-confirmation"
}

Local Studio ports are probed and the most recently focused compatible writable Studio is selected. Studio shows a confirmation before changing the project.

Arguments​

url​

An absolute HTTP or HTTPS URL for the Element Library. The URL is normalized before it is stored.

displayName?​

The label shown in Browse Elements. If omitted, Studio derives a label from the URL.

captionStylesUrl?v4.0.535​

An absolute HTTP or HTTPS URL for a page listing your caption styles. Studio opens this page directly in the Styles tab when generating captions. If omitted, the library is available only in Browse Elements. The URL is normalized before it is stored.

Caption Elements must set isCaptionStyle: true and accept a captions prop.

Iframe context​

Studio appends remotion-studio=true to embedded library URLs. In the caption picker, it also appends remotion-studio-context=captions. Use this context to hide navigation sidebars and show a focused caption selection page:

caption-picker.ts
const params = new URLSearchParams(window.location.search);
const isCaptionPicker =
  params.get('remotion-studio') === 'true' &&
  params.get('remotion-studio-context') === 'captions';

Preserve these query parameters when navigating within your library. The context is a display hint, not an authorization signal. Selecting a style sends its Element payload through installInStudio(); Studio uses it for captions instead of installing it immediately.

Return value​

Returns a promise with a discriminated union.

success​

Indicates whether the request reached the selected Studio tab.

status​

On success, the value is "awaiting-confirmation". This means Studio received the request, not that the config was changed. The user can still decline it.

target​

On success, contains the project name, Studio origin, and Studio version.

code​

On failure, one of:

  • invalid-url
  • invalid-display-name
  • unsupported-origin
  • no-compatible-studio
  • studio-upgrade-required
  • no-configurable-target
  • unsupported-protocol
  • invalid-response
  • target-expired
  • no-config-file
  • request-rejected
  • request-timed-out
  • network-error

message​

A human-readable failure message. Use code for application logic.

Persistence​

After confirmation, Studio adds an object-form Config.addElementLibrary() call to the loaded remotion.config.ts. Existing config source and library entries are preserved.

Element Libraries are identified by their normalized URL. Requesting an already configured URL does not add another call or replace its display name or caption styles URL. To update them, edit the existing config entry.

A project without a loaded remotion.config.ts returns no-config-file.

Supported origins​

The function supports HTTPS websites. HTTP is supported only on localhost and 127.0.0.1 for local development. The Element Library itself must use HTTP or HTTPS.

The confirmation shows the requesting website and the Element Library and caption styles URLs. The Element Library is not added or loaded before confirmation. Adding an Element Library does not install Element source code or dependencies; each Element installation keeps its own confirmation.

Compatibility​

BrowsersEnvironments
Chrome
Firefox
Safari

See also​