customily.js API Reference

customily.js is a browser library that renders real-time product customization previews on an HTML canvas. It exposes a global engraver object that lets you control text, images, vectors, and other personalization elements programmatically.

Use this library when building a fully custom personalization experience instead of embedding the standard Customily iframe.

Quick Start

Use the example below to quickly initialize customily.js and load a personalization template. The following sections explain each step in more detail.

<script src="https://app.customily.com/customily.js"></script>

<div id="fabric-container" style="width: 50%;">
  <canvas id="preview-canvas"></canvas>
</div>

<script>
  engraver.init("preview-canvas", {});
  engraver.setProduct("0313370a-e3d1-4b88-8640-f1027a78235d").then(function () {
    engraver.setText(1, "Hello World");
  });
</script>

Setup

The following steps explain how to initialize customily.js, configure the preview canvas, and load a template.

1. Include the script

<script src="https://app.customily.com/customily.js"></script>

2. Add a canvas inside a sized container

The canvas takes its dimensions from its parent container. Wrap it in a div with a defined width:

<div id="fabric-container" style="width: 50%;">
  <canvas id="preview-canvas"></canvas>
</div>

3. Initialize

var options = {};
engraver.init("preview-canvas", options);

Returns 0 on success, -1 if the canvas element is not found.

4. Load a template

engraver.setProduct("TEMPLATE_ID").then(function () {
  // Template loaded — now you can set text, images, etc.
});

Returns a Promise that resolves when the template is loaded.

Initialization Options

Pass the following options to engraver.init(canvasId, options) to customize the behavior of the preview canvas.

API Reference

The engraver object provides the methods used to customize personalization elements, control the preview canvas, and generate production-ready files.

Element IDs

Most methods require an element ID parameter. This is the unique ID assigned to each personalization element in your template.

To learn how to find an element's ID, see 📄 Element ID

Position Parameter

Some methods use a position parameter to select one of the options configured for a personalization element on the design studio, such as a font, color, preset image, or vector. Positions are 1-based indexes, meaning a value of 1 selects the first available option.

engraver.setFont(1, 2);       // Sets the 2nd font option on text element 1
engraver.setFontColor(3, 1); // Sets the 1st color option on text element 3

For a full explanation of how positions work with element options and libraries, see 📄 Understanding the Position Parameter

Text

Use these methods to update text elements and their appearance.

• setText(id, text) → Number

Sets the text value for a text element.

engraver.setText(1, "John");

Returns 0 on success, -1 on error.

• setFont(id, fontPosition) → Promise<Number>

Sets the font for all text elements matching the given ID.

await engraver.setFont(1, 2); // Apply the 2nd font option

Returns 0 on success, -1 if no matching elements found.

• setFontColor(id, fontColorPosition) → Promise<Number>

Sets the font color for all text elements matching the given ID.

await engraver.setFontColor(1, 0); // Apply the 1st color option

Returns 0 on success, -1 if no matching elements found.

Images

Use these methods to upload images in image placeholders, select preset images from dynamic images, and customize image colors.

• setImage(id, img, threshold) → Promise

Sets a user-uploaded image on an image placeholder.

// From a file input
var reader = new FileReader();
reader.addEventListener("load", function () {
  engraver.setImage(1, reader.result);
});
reader.readAsDataURL(file);

// From a URL
engraver.setImage(1, "https://example.com/photo.jpg");

Returns a Promise that resolves when the image is loaded on the preview.

• setPresetImage(placeholderId, imagePosition) → Promise<void>

Renders a preset image configured for a dynamic image element.

await engraver.setPresetImage(3, 2); // Apply the 2nd preset image

• setImageColor(imageId, colorPosition)

Sets the color of a single-color image element (works both for image placeholders and dynamic images).

engraver.setImageColor(1, 2);

• setImageColorHex(imageId, hexColor)

Sets the color of a single-color image element using a hexadecimal color value.

engraver.setImageColorHex(1, "#ff0000");

Vectors

Use these methods to load vectors into placeholders and update their colors.

• setVector(vectorId, vector)

Loads a vector into a vector placeholder.

engraver.setVector(1, "<svg>...</svg>");       // SVG string
engraver.setVector(1, "https://example.com/file.svg"); // URL
engraver.setVector(1, fileObject);              // File object (EPS, PDF, SVG)

• setPresetVector(vetorId, vectorPosition) → Promise<void>

Renders a preset vector configured for a dynamic vector element.

await engraver.setPresetVector(3, 2); // Apply the 2nd preset vector

• setPresetVectorColor(vectorId, colorPosition) → Promise<void>

Sets the color of a single color vector element using one of its configured color options.

await engraver.setPresetVectorColor(1, 3);

• setPresetVectorColorHex(vectorId, hexColor)

Sets the color of a single color vector element using a hexadecimal color value.

engraver.setPresetVectorColorHex(1, "#00ff00");

Special Elements

Use these methods to generate and customize advanced personalization elements.

• setWordCloud(id, text, shapePosition) → Promise<void>

Generates a word cloud and applies it to an image placeholder.

await engraver.setWordCloud(1, "love family friends happiness");

• setWordSearchPuzzle(id, words) → Promise<{base64, seed}>

Generates a word search puzzle and applies it to a placeholder.

var result = await engraver.setWordSearchPuzzle(1, "cat dog bird fish");
// result.base64 - the puzzle image
// result.seed   - the puzzle seed for reproducibility

• setCalendar(id, date) → Promise<{calendar}>

Sets the calendar displayed on a calendar placeholder.

var result = await engraver.setCalendar(1, new Date(2025, 0, 1));

Export

Use this method to generate production-ready files from the current personalization.

• exportFileAuth(apiKey) → Promise<String>

Exports the current personalized preview to one or more production files.

var fileUrls = await engraver.exportFileAuth("your-api-key");

Returns a Promise that resolves with the URL(s) of the generated file(s), separated by newlines if multiple.

Utilities

These utility methods provide programmatic access to common preview interactions.

• getActionableElements()

Returns the currently selected image placeholder. If none is selected, the first available placeholder is selected and returned.

• setImagePlaceHolderScale()

Programmatically controls the scale of the selected image placeholder.

• setImagePlaceHolderRotation()

Programmatically controls the rotation of the selected image placeholder.

Complete Example

The following example shows a complete implementation of customily.js, including initialization, template loading, text updates, image uploads, and preset image selection.

<html lang="en">
<head>
  <meta charset="utf-8">
</head>
<body>
  <div>
    <input id="textfield1" oninput="processText(1, value)" type="text">
    <input id="imageInput1" type="file" onchange="previewFile(1, id)">
    <select onchange="changePreset(value)">
      <option value="1">Option A</option>
      <option value="2">Option B</option>
    </select>
  </div>

  <script src="https://app.customily.com/customily.js"></script>
  <div id="fabric-container" style="width: 50%;">
    <canvas id="preview-canvas"></canvas>
  </div>

  <script>
    engraver.init("preview-canvas", {});
    engraver.setProduct("0313370a-e3d1-4b88-8640-f1027a78235d").then(function () {
      engraver.setText(1, "Default text");
    });

    function processText(id, value) {
      engraver.setText(id, value);
    }

    function previewFile(placeholderId, fileInputId) {
      var file = document.getElementById(fileInputId).files[0];
      var reader = new FileReader();
      reader.addEventListener("load", function () {
        engraver.setImage(placeholderId, reader.result);
      });
      if (file) {
        reader.readAsDataURL(file);
      }
    }

    function changePreset(value) {
      engraver.setPresetImage(3, parseInt(value));
    }
  </script>
</body>
</html>