Options-Only Mode Integration

Last updated: July 30, 2026

This guide explains how to embed the Customily live preview canvas directly into your product page while using the iframe only for the option set form. This gives you full control over the preview layout and placement while Customily handles the personalization form.

How It Works

In the standard iframe integration (šŸ“„ Standalone modal iframe integration), the entire Customily experience (live preview + personalization form) runs inside a single iframe.

In Options-Only Mode, these two parts are separated:

  • The live preview canvas runs directly on your product page, outside the iframe.

  • The personalization form runs inside a lightweight iframe.

The two communicate using postMessage. When the shopper enters text, selects a font, or uploads an image in the iframe, the live preview canvas on your page updates in real time.

This approach is ideal when you want to:

  • Place the live preview anywhere on your page (for example, as the main product image)

  • Control the preview size and aspect ratio

  • Avoid having the preview constrained inside an iframe

The integration works as follows:

  1. Add a <div> where the live preview canvas will be rendered.

  2. Load the customilyPreviewHost.js script, which loads the Customily engraver and creates the live preview canvas

  3. Add an iframe using your Customily personalization link with mode=options-only.

  4. The iframe sends personalization updates through engraver commands to the parent page via postMessage.

  5. TheĀ customilyPreviewHost.jsĀ script executes those commands on the local engraver, updating the preview

Implementation

Follow the steps below to embed the live preview on your page while displaying the personalization form inside an iframe.

Add the Canvas Container and the Options Iframe

Add a container where the live preview canvas will be rendered, then embed your Customily personalization link in an iframe using mode=options-only.

<!-- Live preview canvas renders here -->
<div id="customily-canvas" style="width: 500px; height: 500px;"></div>

<!-- Option set form (no live preview, just the form) -->
<iframe
    id="customily-options"
    src="https://preview-2.customily.com/productViewer?template={TEMPLATE_ID}&set={OPTION_SET_ID}&shop={STORE_URL}&mode=options-only"
    style="width: 400px; height: 600px; border: none;">
</iframe>

Important

See theĀ &mode=options-onlyĀ appended at the end of the iframeĀ srcĀ URL ā€” this is what tells Customily to render only the option set form without the live preview canvas. Without it, the iframe would load the full experience (canvas + form) as usual.

Configure and Load the Canvas Host

Configure the canvas host by specifying the canvas container and the options iframe, then load the customilyPreviewHost.js script.

<script>
    // Configure the canvas host before loading the script
    window.customilyCanvasHost = {
        canvasContainerId: 'customily-canvas',    // ID of the div where the canvas will render
        iframeSelector: '#customily-options',      // CSS selector for the options iframe
        onReady: () => {
            console.log('Customily canvas is ready');
        }
    };
</script>

<!-- Load the canvas host script -->
<script src="https://preview-2.customily.com/static/js/customilyPreviewHost.js"></script>

TheĀ customilyPreviewHost.jsĀ script:

  1. Loads the Customily engraver (customily.js)

  2. Creates a canvas element inside your container div

  3. Listens forĀ postMessageĀ commands from the options iframe

  4. Executes engraver operations (such as updating text or loading images) on the local canvas

Configuration Options

Configure the preview host by setting the following properties on window.customilyCanvasHost before loading the customilyPreviewHost.js script.

Option

Type

Required

Description

canvasContainerId

string

Yes

ID of the HTML element where the canvas will be created

iframeSelector

string

Yes

CSS selector for the options-only iframe

engraverUrl

string

No

Override the URL forĀ customily.jsĀ (defaults to the Customily CDN). Useful if you want to self-hostĀ customily.jsĀ on your own server or CDN to reduce loading times.

onReady

function

No

Callback fired when the engraver is initialized and ready

Complete Example

This example places the canvas and options iframe side by side:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Options-Only Mode Test</title>
    <style>
        body { font-family: sans-serif; margin: 20px; }
        .container {
            display: flex;
            gap: 20px;
            align-items: flex-start;
        }
        .panel { display: flex; flex-direction: column; }
        #customily-canvas {
            width: 500px;
            height: 500px;
            border: 1px solid #ccc;
        }
        #customily-options {
            width: 500px;
            height: 600px;
            border: 1px solid #ccc;
        }
    </style>
</head>
<body>
    <div class="container">
        <div class="panel">
            <h2>Canvas (parent page)</h2>
            <div id="customily-canvas"></div>
        </div>
        <div class="panel">
            <h2>Options (iframe)</h2>
            <iframe
                id="customily-options"
                src="https://preview-2.customily.com/productViewer?template=0313370a-e3d1-4b88-8640-f1027a78235d&set=53b7ddcc-880d-4303-a495-0338e1388ca2&shop=standalone.customily.com&mode=options-only"
            ></iframe>
        </div>
    </div>

    <script>
        window.customilyCanvasHost = {
            canvasContainerId: 'customily-canvas',
            iframeSelector: '#customily-options',
            onReady: function() {
                console.log('Canvas host is ready!');
            }
        };
    </script>
    <script src="https://preview-2.customily.com/static/js/customilyPreviewHost.js"></script>

    <script>
        // Listen for personalization data (same as the standard iframe integration)
        window.addEventListener('message', (event) => {
            const data = event.data;
            if (data?.action !== 'add-to-cart') return;

            console.log('Personalization complete:', data);
            // Add to your platform's cart here...
        });
    </script>
</body>
</html>

Add to Cart

Options-Only Mode doesn't change the add-to-cart flow. When the shopper clicks Add to Cart, the iframe sends the same postMessage containing the personalization data as in the standard iframe integration.

To capture the personalization data and add the product to your platform's cart, follow the Capture Personalization Data section of the Standalone Modal Iframe Integration guide.