Controlling the Embed

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