Controlling the Embed

Dynamically update template content and switch templates via postMessage

Control the embed from your parent page using postMessage. You can switch templates and update layer content (text, images) without reloading the iframe.

Setting Layer Modifications#

Update text and image layers dynamically:

const iframe = document.querySelector("iframe");

iframe.contentWindow.postMessage(
  {
    type: "orshot:embed:control",
    modifications: {
      text: "Hello World",
      image: "https://example.com/photo.jpg",
    },
  },
  "*"
);

The modifications object uses layer parameter names as keys. These match the parameter names you've defined in your template.

Switching Templates#

Switch to a different template within the same embed:

iframe.contentWindow.postMessage(
  {
    type: "orshot:embed:control",
    templateId: "481",
  },
  "*"
);

Switch Template + Set Modifications#

Combine both to load a specific template with pre-filled values:

iframe.contentWindow.postMessage(
  {
    type: "orshot:embed:control",
    templateId: "481",
    modifications: {
      title: "My Custom Title",
      subtitle: "Product description here",
      image: "https://example.com/product.jpg",
    },
  },
  "*"
);

The embed will:

Switch to the specified template
Wait for it to load
Apply the layer modifications

URL Parameters vs postMessage#

You can also set initial values via URL parameters:

<iframe
  src="https://orshot.com/embeds/abc?templateId=481&title=Hello&image=https://..."
/>

Method	Use Case
URL params	Initial load with pre-filled values
postMessage	Dynamic updates without reload

Complete Example#

class EmbedController {
  constructor(iframe) {
    this.iframe = iframe;
  }

  // Update layer values
  setModifications(modifications) {
    this.iframe.contentWindow.postMessage(
      {
        type: "orshot:embed:control",
        modifications,
      },
      "*"
    );
  }

  // Switch to a different template
  switchTemplate(templateId) {
    this.iframe.contentWindow.postMessage(
      {
        type: "orshot:embed:control",
        templateId,
      },
      "*"
    );
  }

  // Switch template and set values
  loadTemplate(templateId, modifications) {
    this.iframe.contentWindow.postMessage(
      {
        type: "orshot:embed:control",
        templateId,
        modifications,
      },
      "*"
    );
  }
}

// Usage
const controller = new EmbedController(document.querySelector("iframe"));

// Update current template
controller.setModifications({
  headline: "New Headline",
  background: "https://example.com/bg.jpg",
});

// Switch to template 481 with custom values
controller.loadTemplate("481", {
  title: "Product Launch",
  price: "$99",
  image: "https://example.com/product.jpg",
});

React Example#

import { useRef, useCallback } from "react";

function useEmbedController() {
  const iframeRef = useRef(null);

  const setModifications = useCallback((modifications) => {
    iframeRef.current?.contentWindow?.postMessage(
      {
        type: "orshot:embed:control",
        modifications,
      },
      "*"
    );
  }, []);

  const loadTemplate = useCallback((templateId, modifications = {}) => {
    iframeRef.current?.contentWindow?.postMessage(
      {
        type: "orshot:embed:control",
        templateId,
        modifications,
      },
      "*"
    );
  }, []);

  return { iframeRef, setModifications, loadTemplate };
}

// Usage
function Editor() {
  const { iframeRef, setModifications, loadTemplate } = useEmbedController();

  return (
    <div>
      <iframe
        ref={iframeRef}
        src="https://orshot.com/embeds/abc123?templateId=481"
      />

      <button onClick={() => setModifications({ title: "Updated!" })}>
        Update Title
      </button>

      <button onClick={() => loadTemplate("500", { title: "New Template" })}>
        Switch Template
      </button>
    </div>
  );
}

Requirements#

SaaS plan or higher — This feature requires the SaaS plan or above
Enable Events must be turned on in your embed settings
Your domain must be in the embed's allowed domains list
Layer parameter names in modifications must match your template's defined parameters
templateId must reference a template that exists in the embed's workspace

Ready to automate?

Start rendering images, PDFs and videos from your templates in under 2 minutes. Free plan, no credit card.

Get your API key

Image, PDF and video generation via API
Visual editor with AI and smart layouts
Zapier, Make, MCP and 50+ integrations
White-label embed for your own app
60 free renders — no credit card required