Create Your First Lottie Creator Plugin with React

This guide builds on the same concepts from the HTML and JS tutorial, but with tooling that makes development easier:

• Hot reloading for instant feedback

• Preconfigured local server

• TypeScript for type safety and autocomplete

• Vite for managing plugin builds

Step 1: Create your plugin

npm create @lottiefiles/creator-plugin

The CLI walks you through a few prompts:

• Package name — the npm package name. It also becomes the new folder name. Enter my-plugin to follow along.

• Plugin name — the display name shown in Lottie Creator.

• Install dependencies? — choose Yes to install everything automatically.

This creates a new my-plugin/ folder in the current directory with everything configured. To name the folder explicitly, you can also pass it as an argument: npm create @lottiefiles/creator-plugin my-plugin.

Step 2: Understand the project structure

my-plugin/
├── plugin/
│   ├── manifest.json    # Plugin metadata
│   └── plugin.ts        # Plugin code (TypeScript)
├── src/
│   ├── app.tsx          # UI code (React)
│   └── main.tsx         # React entry point
├── index.html
├── package.json
└── vite.config.ts

src/app.tsx:

function App() {
  const handleClick = () => {
    // Send a message to the plugin code
    parent.postMessage({ pluginMessage: { type: "create-rectangle" } }, "*");
  };

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

plugin/plugin.ts:

creator.ui.show({ width: 300, height: 400 });

// Listen for messages from the UI
creator.ui.onMessage((msg) => {
  if (msg.type === "create-rectangle") {
    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 },
    });
  }
});

What's happening

When you click the button in your UI:

1. The React component sends a message via parent.postMessage()

2. Your plugin code receives it via creator.ui.onMessage()

3. The plugin uses the creator API to create a shape in the scene

This message-passing pattern is how all plugins work — the UI and plugin code are separate for security, but they communicate freely through messages.

TypeScript types

The scaffolding installs @lottiefiles/creator-api-types, which provides type definitions for the global creator object and every API symbol documented in the Creator API reference. If you're adding plugin support to an existing project, install it manually:

npm add -D @lottiefiles/creator-api-types

Then expose the types to your plugin code by adding the package to typeRoots in your tsconfig.json:

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@lottiefiles/creator-api-types", "./node_modules/@types"]
  }
}

After this, creator, Scene, Layer, Shape, and the rest of the API are available with full autocomplete and type checking.

Step 3: Run the dev server

cd my-plugin
npm run dev

If you skipped the install prompt, run npm install first.

You'll see output like:

➜ Local: https://localhost:5173/

Step 4: Load in Lottie Creator

1. Open Lottie Creator

2. Open the Plugins panel from the left sidebar and click the + button

3. On the Develop tab, enter https://localhost:5173 under Development URL and click Continue

Your plugin should open immediately.

Step 5: Make changes

Any changes you make to the UI or plugin code will be automatically reflected on the local server.

For example, here's how to edit plugin/plugin.ts to add animation to the rectangle:

creator.ui.show({ width: 300, height: 400 });

creator.ui.onMessage((msg) => {
  if (msg.type === "create-rectangle") {
    const layer = creator.activeScene.createShapeLayer();
    layer.createRectangle();

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

    // add animation keyframes
    layer.position.addKeyframes([
      { frame: 0, value: { x: 100, y: 100 } },
      { frame: 30, value: { x: 300, y: 100 } },
      { frame: 60, value: { x: 300, y: 300 } },
    ]);
  }
});

Save the file — your plugin reloads automatically.

Example

Basic plugin (React) example →