How Plugins Work

For security purposes, Lottie Creator plugins are separated into a plugin sandbox (where your plugin code runs), and a UI iframe (where your plugin interface lives).

Your plugin sandbox and UI can communicate with each other via postmessage.

Plugin architecture

Here's how Lottie Creator, your plugin sandbox, and your plugin UI connect:

Here's the difference between the plugin sandbox and the UI iframe:

	Plugin sandbox	UI iframe
Runs	Your plugin code (`plugin.ts/plugin.js`)	Your interface (`App.tsx` or HTML)
Has access to	Creator APIs	Browser APIs
Can	Read/modify layers, shapes, keyframes Control the timeline Access user selection Store plugin data	Render UI with React, Vue, or plain HTML Make network requests (fetch) Handle user input
Cannot	Directly update the DOM Access browser APIs	Access Creator APIs Access the animation scene

Communication between UI and plugin

The two parts communicate through message passing. For example, here's how we might set up a plugin that creates a rectangle when you click on a button:

1. UI sends a message to the plugin

When the user clicks the button, the UI sends a message to the plugin sandbox using parent.postMessage().

// In plugin UI (App.tsx)

function App() {
  const createRectangle = () => {
    // send a message to the plugin sandbox (must wrap in pluginMessage)
    parent.postMessage({ pluginMessage: { type: "create-rectangle" } }, "*");
  };

  return <button onClick={createRectangle}>Create Rectangle</button>;
}

2. Plugin receives the message and responds

The plugin sandbox listens for messages using creator.ui.onMessage(). When it receives the message, it can use the creator API to modify the scene, then send a response back to the UI.

// In plugin sandbox (plugin.ts)

creator.ui.onMessage((message) => {
  // receive the message from the UI
  if (message.type === "create-rectangle") {
    // use the creator API to create a shape layer with a rectangle shape
    const layer = creator.activeScene.createShapeLayer({
      position: { x: 100, y: 100 },
    });
    layer.createRectangle({ size: { width: 200, height: 200 } });

    const fill = layer.createFill({
      type: "SOLID",
      color: { r: 0, g: 255, b: 0 },
    });

    // send a response back to the UI
    creator.ui.postMessage({ type: "success" });
  }
});

3. UI receives the response

The UI listens for messages from the plugin using window.addEventListener('message', ...).

// In plugin UI (App.tsx)

useEffect(() => {
  const handler = (event: MessageEvent) => {
    // extract the plugin message from the event (messages are wrapped in pluginMessage)
    const message = event.data.pluginMessage;

    if (message?.type === "success") {
      console.log("Rectangle created!");
    }
  };

  // listen for messages from the plugin sandbox
  window.addEventListener("message", handler);
  return () => window.removeEventListener("message", handler);
}, []);