Contact us
Skip to main content

Interface: IHeadlessEditor

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:62

Public API of the headless editor.

IHeadlessEditor

Example​

const editor = document.querySelector('au-headless-editor') as IHeadlessEditor;

// Initialization
await editor.init(config);

// Changing the active product
const product = await editor.openProduct({ productId: 12345 });

// Selecting a variant
const variant = await editor.setVariantById(67890);

// Triggering the add-to-cart event
const lineItem = await editor.addToCart();

Extends​

  • IWorkflowElement

Properties​

injector?​

optional injector?: Injector

Defined in: workflow-elements-types/workflow-element-base/workflow-element.d.ts:7

Inherited from​

IWorkflowElement.injector

Methods​

addToCart()​

addToCart(): Promise<LineItem>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:306

Saves the design and triggers the add-to-cart event

Returns​

Promise<LineItem>

A cart line item containing product information

Throws​

If saving the design fails

Example​

const lineItem = await editor.addToCart();
console.log(lineItem.productId, lineItem.quantity);

applyContainerSettingsToCurrentSurface()​

applyContainerSettingsToCurrentSurface(updatedContainer): Promise<Container>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:760

Applies updated container settings to the current surface.

Parameters​

updatedContainer​

Partial<Container>

The modified container object. It is recommended to obtain the base object via getCurrentSurfaceContainerSettings(), modify its properties, and pass it back.

Returns​

Promise<Container>

A promise resolving to the successfully applied container settings.

Remarks​

Use this method to programmatically change the appearance or state of the surface's base container. Typical scenarios include toggling visibility, changing the container type (e.g., to 'Colorless'), or updating visualization properties such as texture opacity.

Throws​

If the container is invalid, not found, or the update fails.

Example​

// 1. Get current settings
const container = editor.getCurrentSurfaceContainerSettings();

// 2. Modify properties
container.type = 'Colorless';
container.visible = true;
container.visualization = {
  type: "TextureVisualization",
  opacity: 0.5,
  enableGlareEffect: false,
};

// 3. Apply changes
await editor.applyContainerSettingsToCurrentSurface(container);

applyToggleToCurrentDesign()​

applyToggleToCurrentDesign(toggleId, toggleParamLabel, toggleParamValue?): Promise<ToggleSet>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:707

Applies a specific toggle value to the current design.

Parameters​

toggleId​

string

The ID of the Toggle to apply. Obtain it from getCurrentDesignToggleSet().

toggleParamLabel​

string

The label of the parameter value to apply (e.g., "Red", "Roboto Bold"). Must match one of the label values in the Toggle's params array.

toggleParamValue?​

string

Optional custom value for TEXT toggles. If provided, overrides the predefined text content of the selected parameter.

Returns​

Promise<ToggleSet>

A promise resolving to the updated Toggle Set after applying the toggle.

Throws​

If the toggle or parameter is not found, or applying fails.

Examples​

// Apply a color toggle
const toggleSet = await editor.getCurrentDesignToggleSet();
const colorToggle = toggleSet.toggles.find(t => t.name === "Primary Color");

await editor.applyToggleToCurrentDesign(colorToggle.id, "Red");
// Apply a font toggle
const fontToggle = toggleSet.toggles.find(t => t.name === "Heading Font");
await editor.applyToggleToCurrentDesign(fontToggle.id, "Roboto Bold");
// Apply a TEXT toggle with custom user input
const textToggle = toggleSet.toggles.find(t => t.name === "Custom Message");
await editor.applyToggleToCurrentDesign(
  textToggle.id,
  "Default Message",
  "Happy Birthday, John!" // custom text overrides the default
);

getChoices()​

getChoices(): Choice<string | string[]>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:102

Returns the currently selected product options

Returns​

Choice<string | string[]>

Current selections or undefined if no product is loaded

Example​

const choices = editor.getChoices();
console.log(choices); // { "1": "red", "2": ["small", "medium"] }

Overrides​

IWorkflowElement.getChoices

getChoicesValues()​

getChoicesValues(): ChoiceValue

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:114

Returns the values of the selected options (option names and values)

Returns​

ChoiceValue

An object with option names and their values

Example​

const values = editor.getChoicesValues();
console.log(values); // { "Color": "Red", "Size": ["Small", "Medium"] }

Overrides​

IWorkflowElement.getChoicesValues

getCurrentDesignPermanentPreview()​

getCurrentDesignPermanentPreview(surface?): Promise<string>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:405

Returns a single permanent preview URL for the specified surface of the current design.

Parameters​

surface?​

ISurfaceOptions

Surface selection options (surfaceIndex, surfaceId, or surfaceName). If not specified, the current active surface is used.

Returns​

Promise<string>

A promise resolving to the permanent preview URL, or null if generation fails.

Throws​

If saving the design or generating the preview fails.

Example​

// Get permanent preview for the current surface
const previewUrl = await editor.getCurrentDesignPermanentPreview();

// Get permanent preview for a specific surface by index
const previewUrl = await editor.getCurrentDesignPermanentPreview({ surfaceIndex: 0 });

// Get permanent preview for a specific surface by id
const previewUrl = await editor.getCurrentDesignPermanentPreview({ surfaceId: "a6ab7678-a673-4a1d-95dc-d44e22aaf86e" });

// Get permanent preview for a specific surface by name
const previewUrl = await editor.getCurrentDesignPermanentPreview({ surfaceName: "Front" });

console.log(previewUrl); // "https://api.customerscanvashub.com/..."

getCurrentDesignPermanentPreviews()​

getCurrentDesignPermanentPreviews(surface?): Promise<string[]>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:430

Returns an array of permanent preview URLs for the specified surface of the current design.

Parameters​

surface?​

ISurfaceOptions

Surface selection options (surfaceIndex, surfaceId, or surfaceName). If not specified, previews are generated for all surfaces.

Returns​

Promise<string[]>

A promise resolving to an array of permanent preview URLs.

Throws​

If saving the design or generating the previews fails.

Example​

// Get all permanent previews for the current surface
const previewUrls = await editor.getCurrentDesignPermanentPreviews();
previewUrls.forEach(url => console.log(url));

// Get permanent previews for a specific surface
const previewUrls = await editor.getCurrentDesignPermanentPreviews({ surfaceIndex: 0 });

// Use case: Generate thumbnails for all mockups on a surface
const thumbnails = await editor.getCurrentDesignPermanentPreviews({ surfaceName: "Front" });
thumbnails.forEach((url, index) => {
  console.log(`Mockup ${index + 1}: ${url}`);
});

getCurrentDesignPrintProductModel()​

getCurrentDesignPrintProductModel(): PrintProduct

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:828

Returns the full low-level Print Product model of the current design.

Returns​

PrintProduct

The complete Print Product model.

Remarks​

Advanced API: This method provides direct access to the raw PrintProduct model from Design Atoms, opening deep access to all surfaces, containers, and design elements. Use it only when high-level methods (such as getCurrentSurfaceTextItems, getCurrentSurfaceImagePlaceholderItems, or getCurrentSurfaceQrCodeItems) are insufficient for your specific programmatic manipulation tasks.

Modifying the returned object does not affect the design until you pass it back through setCurrentDesignPrintProductModel().

Throws​

If the design is not loaded or the model cannot be obtained.

Example​

// Inspect the raw product structure
const printProduct = editor.getCurrentDesignPrintProductModel();

printProduct.surfaces.forEach((surface, index) => {
  console.log(`Surface ${index}: ${surface.name}`);
  surface.containers.forEach(container => {
    console.log(`  Container has ${container.items.length} items`);
  });
});

getCurrentDesignTempPreview()​

getCurrentDesignTempPreview(surface?): Promise<string>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:455

Returns a temporary preview base64 URL for the specified surface of the current design.

Parameters​

surface?​

ISurfaceOptions

Surface selection options (surfaceIndex, surfaceId, or surfaceName). If not specified, the current active surface is used.

Returns​

Promise<string>

A promise resolving to the temporary preview URL as a data URL (base64).

Throws​

If generating the preview fails.

Example​

// Get temporary preview for the current surface
const tempPreviewUrl = await editor.getCurrentDesignTempPreview();
document.getElementById('preview').src = tempPreviewUrl; // data:image/png;base64,...

// Get temporary preview for a specific surface
const tempPreviewUrl = await editor.getCurrentDesignTempPreview({ surfaceIndex: 0 });

// Use case: Real-time preview update without saving
async function updatePreview() {
  const preview = await editor.getCurrentDesignTempPreview({ surfaceName: "Back" });
  displayPreview(preview);
}

getCurrentDesignTempPreviews()​

getCurrentDesignTempPreviews(): Promise<string[]>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:480

Returns an array of temporary preview base64 URLs for all surfaces of the current design.

Returns​

Promise<string[]>

A promise resolving to an array of temporary preview URLs (one per surface).

Throws​

If generating the previews fails.

Example​

// Get temporary previews for all surfaces
const allPreviews = await editor.getCurrentDesignTempPreviews();
allPreviews.forEach((url, index) => {
  console.log(`Surface ${index}: ${url}`);
});

// Use case: Generate a thumbnail gallery for all surfaces
const gallery = document.getElementById('gallery');
const previews = await editor.getCurrentDesignTempPreviews();
previews.forEach(previewUrl => {
  const img = document.createElement('img');
  img.src = previewUrl;
  gallery.appendChild(img);
});

getCurrentDesignToggleSet()​

getCurrentDesignToggleSet(): Promise<ToggleSet>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:668

Returns the Toggle Set for the current design.

Returns​

Promise<ToggleSet>

A promise resolving to the Toggle Set of the current design.

Throws​

If the design has no Toggle Set or loading fails.

Examples​

// Get the Toggle Set and inspect available toggles
const toggleSet = await editor.getCurrentDesignToggleSet();

toggleSet.toggles.forEach(toggle => {
  console.log(`Toggle: ${toggle.name} (${toggle.type})`);
  toggle.params.forEach(param => {
    console.log(`Label - ${param.label}`);
  });
});
// Build a color palette UI from a COLOR toggle
const toggleSet = await editor.getCurrentDesignToggleSet();
const colorToggle = toggleSet.toggles.find(t => t.type === 'color');

if (colorToggle) {
  colorToggle.params.forEach(colorParam => {
    renderColorButton(colorParam.label, colorParam.previewColor, () => {
      editor.applyToggleToCurrentDesign(colorToggle.id, colorParam.label);
    });
  });
}

getCurrentDesignVariant()​

getCurrentDesignVariant(): DesignVariant

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:252

Returns the current design variant

Returns​

DesignVariant

The current design variant

Example​

const designVariant = editor.getCurrentDesignVariant();

getCurrentProduct()​

getCurrentProduct(): Product

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:155

Returns the currently loaded product

Returns​

Product

The current product

Throws​

If no product is loaded

Example​

const product = editor.getCurrentProduct();
console.log(product.name);

getCurrentSurface()​

getCurrentSurface(): Surface

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:293

Returns the currently active surface

Returns​

Surface

The current surface

Example​

const surface = editor.getCurrentSurface();
console.log(surface.name);

getCurrentSurfaceBarcodeItems()​

getCurrentSurfaceBarcodeItems(options?): IBarcodeItem<BarcodeSubType, BarcodeFormat>[]

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:590

Returns a list of QR code and barcode items on the current surface of the active design.

Parameters​

options?​

IBarcodeOptions

Optional filtering options. Use containerId to filter items within a specific container.

Returns​

IBarcodeItem<BarcodeSubType, BarcodeFormat>[]

An array of QR code/barcode items enriched with schema data.

Example​

// Get all QR codes and barcodes on the current surface
const qrCodes = editor.getCurrentSurfaceBarcodeItems();

// Get QR codes filtered by a specific container
const containerQrCodes = editor.getCurrentSurfaceBarcodeItems({ containerId: "container-123" });

// Example: Find a specific VCard QR code and read its structured data
const vCardQr = qrCodes.find(qr => qr.subType === BarcodeSubType.V_CARD && qr.name === "ContactQR");
if (vCardQr && vCardQr.data.firstName) {
  console.log(`Found contact: ${vCardQr.data.firstName} ${vCardQr.data.lastName}`);
}

getCurrentSurfaceContainerSettings()​

getCurrentSurfaceContainerSettings(): Container

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:727

Returns the container settings for the current surface.

Returns​

Container

The current container settings.

Remarks​

A container represents the base layer or background of a surface (e.g., a full-color background, a limited-palette container, or a transparent/colorless container). This method allows you to inspect its current configuration, including visibility, type, and visualization settings (such as textures or glare effects).

Throws​

If the container for the current surface is not found.

Example​

// Get current container settings
const container = editor.getCurrentSurfaceContainerSettings();
console.log(`Type: ${container.type}, Visible: ${container.visible}`);

getCurrentSurfaceImagePlaceholderItems()​

getCurrentSurfaceImagePlaceholderItems(options?): PlaceholderItem[]

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:354

Returns a list of image placeholders for the current surface of the active design.

Parameters​

options?​

IPlaceholderOptions

Optional filtering options. Use containerId to filter placeholders within a specific container (similar to text item filtering).

Returns​

PlaceholderItem[]

An array of image placeholder items enriched with schema data.

Example​

// Get all image placeholders on the current surface
const placeholders = editor.getCurrentSurfaceImagePlaceholderItems();

// Get placeholders filtered by a specific container
const containerPlaceholders = editor.getCurrentSurfaceImagePlaceholderItems({ containerId: "container-123" });

console.log(placeholders[0].schemaDefinition); // { title: "...", prompt: "...", required: true, ... }

getCurrentSurfaces()​

getCurrentSurfaces(): Surface[]

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:281

Returns all surfaces of the current product

Returns​

Surface[]

An array of all surfaces

Example​

const surfaces = editor.getCurrentSurfaces();
surfaces.forEach(s => console.log(s.name));

getCurrentSurfaceTextItems()​

getCurrentSurfaceTextItems(options?): TextItem[]

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:335

Returns the text items of the current surface along with their schemas

Parameters​

options?​

ITextItemOptions

Text item filtering options (optional)

Returns​

TextItem[]

An array of text items

Example​

const textItems = editor.getCurrentSurfaceTextItems();
textItems.forEach(item => console.log(item.text));

// With filtering
const filtered = editor.getCurrentSurfaceTextItems({ schemaName: "Title" });

getCurrentVariant()​

getCurrentVariant(): ProductVariant

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:207

Returns the currently selected product variant

Returns​

ProductVariant

The current product variant

Throws​

If no variant is selected

Example​

const variant = editor.getCurrentVariant();
console.log(variant.sku);

getFitCropperData()​

getFitCropperData(imageSize, targetAspectRatio): CropperData

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:967

Calculates the initial cropper frame data so that it perfectly fits the target aspect ratio and is centered relative to the original image.

This utility saves integrators from having to manually implement the scaling and centering math for the frame.

Parameters​

imageSize​

ISize

The dimensions (width and height) of the original image.

targetAspectRatio​

number

The target aspect ratio (width / height) of the placeholder.

Returns​

CropperData

A CropperData object with the calculated frame coordinates, dimensions, and a zoom scale of 1.

Example​

const imageSize = { width: 800, height: 600 };
const targetAspectRatio = 1; // Square placeholder (1:1)

const initialCropData = editor.getFitCropperData(imageSize, targetAspectRatio);
// Result: {
//   framePosition: { x: 100, y: 0 },
//   frameSize: { width: 600, height: 600 },
//   zoomScale: 1
// }

getImagePlaceholderAllowedImages()​

getImagePlaceholderAllowedImages(placeholder, includeSubfolders?, skip?, take?): Promise<Image[]>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:379

Retrieves a paginated list of allowed images that can be applied to a specific image placeholder.

Parameters​

placeholder​

PlaceholderItem

The PlaceholderItem.

includeSubfolders?​

boolean

If true, the search will include images from nested subfolders. Defaults to false.

skip?​

number

The number of items to skip for pagination (offset).

take?​

number

The maximum number of items to return (limit).

Returns​

Promise<Image[]>

A promise resolving to an array of Image objects containing metadata and preview URLs.

Example​

const placeholders = editor.getCurrentSurfaceImagePlaceholderItems();
const targetPlaceholder = placeholders.find(p => p.name === "MainImagePlaceholder");

if (targetPlaceholder) {
  // Fetch the first 10 allowed images, including subfolders
  const images = await editor.getImagePlaceholderAllowedImages(targetPlaceholder, true, 0, 10);

  images.forEach(img => {
    console.log(img.name, img.previews["headless-editor-400-400"]);
  });
}

getImagePlaceholderContent()​

getImagePlaceholderContent(targetItemId): Promise<PlaceholderContent>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:901

Returns the current image content of a specific image placeholder as a Blob.

Parameters​

targetItemId​

string

The ID of the image placeholder. Obtain it from getCurrentSurfaceImagePlaceholderItems().

Returns​

Promise<PlaceholderContent>

A promise resolving to the image content as a Blob.

Remarks​

This method is useful when you need to download, preview, or further process the image currently assigned to a placeholder. If the design has not been saved to a private state yet, it will be saved automatically before extracting the content.

The returned Blob can be converted to a data URL via URL.createObjectURL() for immediate display in an <img> tag, or uploaded to your own backend.

Throws​

If the placeholder is not found, has no assigned image, or an error occurs during extraction.

Example​

// Download the current placeholder image
const placeholders = editor.getCurrentSurfaceImagePlaceholderItems();
const mainImage = placeholders.find(p => p.name === "MainImage");

if (mainImage) {
  const blob = await editor.getImagePlaceholderContent(mainImage.id);
  const url = URL.createObjectURL(blob);

  // Display in an <img> element
  const img = document.createElement('img');
  img.src = url;
  document.body.appendChild(img);

  // Or trigger a download
  const link = document.createElement('a');
  link.href = url;
  link.download = 'placeholder-image.png';
  link.click();
}

getLineItem()​

getLineItem(): Promise<LineItem>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:319

Saves the design and returns a cart line item without adding it to the cart

Returns​

Promise<LineItem>

A cart line item containing product information

Throws​

If saving the design fails

Example​

const lineItem = await editor.getLineItem();
console.log(lineItem.properties);

init()​

init(configuration, forceReset?): Promise<boolean>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:79

Initializes the editor with the specified configuration

Parameters​

configuration​

IHeadlessEditorInitArgs

Configuration for initializing the editor

forceReset?​

boolean

Forces a state reset (optional)

Returns​

Promise<boolean>

true if initialization is successful, false if it fails

Throws​

If the configuration is invalid

Example​

const success = await editor.init({
  input: { productId: 12345 },
  integration: { tenantId: 'tenant', token: 'token', user: { id: 'user' } }
});

Overrides​

IWorkflowElement.init

openProduct()​

openProduct(input): Promise<Product>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:142

Opens a product in the editor by productId or productReferenceId

Parameters​

input​

OpenProductInput

Input data for opening the product

Returns​

Promise<Product>

The loaded product

Throws​

If the product is not found or a loading error occurs

Example​

const product = await editor.openProduct({ productId: 12345 });
// or
const product = await editor.openProduct({ productReferenceId: "external-ref" });

resetImagePlaceholderContent()​

resetImagePlaceholderContent(targetItemId): Promise<void>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:798

Clears the image content of a specific image placeholder on the current surface.

Parameters​

targetItemId​

string

The ID of the image placeholder to clear. Obtain it from getCurrentSurfaceImagePlaceholderItems().

Returns​

Promise<void>

A promise that resolves when the content has been successfully cleared.

Remarks​

This method removes the currently assigned image from the target placeholder. If the placeholder is configured with a default stub image in the Design template, the stub will be restored automatically instead of leaving the placeholder empty.

Use this method when you need to programmatically revert a placeholder to its initial state, for example, when the customer clicks a "Reset" button in your customization UI.

Throws​

If the placeholder is not found or an error occurs during the update.

Examples​

// Find the target placeholder
const placeholders = editor.getCurrentSurfaceImagePlaceholderItems();
const mainImagePlaceholder = placeholders.find(p => p.name === "MainImage");

if (mainImagePlaceholder) {
  // Clear the current image (restores stub if configured)
  await editor.resetImagePlaceholderContent(mainImagePlaceholder.id);
}
// Reset all image placeholders on the current surface
const placeholders = editor.getCurrentSurfaceImagePlaceholderItems();
await Promise.all(
  placeholders.map(p => editor.resetImagePlaceholderContent(p.id))
);

setBarcodeItemContent()​

setBarcodeItemContent<SubType, Format>(targetItemId, subType, format, content): void

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:633

Updates the content and configuration of a specific QR code or barcode item on the current surface.

Type Parameters​

SubType​

SubType extends BarcodeSubType

Format​

Format extends BarcodeFormat

Parameters​

targetItemId​

string

The ID of the QR code/barcode item to update.

subType​

SubType

The specific content subtype of the code (e.g., BarcodeSubType.V_CARD, BarcodeSubType.URL).

format​

Format

The barcode/QR code format (e.g., BarcodeFormat.QR_CODE, BarcodeFormat.EAN_13).

content​

BarcodeData<SubType, Format>

The data payload. Its structure is strictly inferred from the subType and format generics.

Returns​

void

Throws​

If the target item is not found or the provided data is invalid.

Example​

// Example 1: Update a simple URL QR code
const urlQr = editor.getCurrentSurfaceBarcodeItems().find(qr => qr.name === "WebsiteQR");
if (urlQr) {
  editor.setBarcodeItemContent(
    urlQr.id,
    BarcodeSubType.URL,
    BarcodeFormat.QR_CODE,
    { value: "https://example.com" }
  );
}

// Example 2: Update a complex VCard QR code with structured data
const contactQr = editor.getCurrentSurfaceBarcodeItems().find(qr => qr.name === "ContactQR");
if (contactQr) {
  editor.setBarcodeItemContent(
    contactQr.id,
    BarcodeSubType.V_CARD,
    BarcodeFormat.QR_CODE,
    {
      firstName: "Test first name",
      lastName: "Test last name",
      organization: "Aurigma",
      email: "test@aurigma.com",
      mobilePhone: "04805718146",
      url: "https://customerscanvashub.com"
    }
  );
}

setChoices()​

setChoices(choices): Promise<ProductVariant>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:127

Sets the selected product options and returns the corresponding variant

Parameters​

choices​

Choice<string | string[]>

An object with option selections (key is option ID, value is value ID)

Returns​

Promise<ProductVariant>

The product variant matching the selected options

Throws​

If the variant is not found or an error occurs

Example​

const variant = await editor.setChoices({ "1": 101, "2": [201, 202] });

Overrides​

IWorkflowElement.setChoices

setCurrentDesignPrintProductModel()​

setCurrentDesignPrintProductModel(product): void

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:860

Updates the design by applying a modified Print Product model back into the Headless Editor.

Parameters​

product​

PrintProduct

The modified PrintProduct model to apply.

Returns​

void

Remarks​

Advanced API: Use this method to apply structural changes or property modifications made directly to the PrintProduct model. This is useful for complex or bulk modifications that are not covered by standard high-level API methods.

Be cautious when modifying the model directly — invalid changes may corrupt the design state. Always obtain the current model via getCurrentDesignPrintProductModel() before making modifications.

Throws​

If the provided model is invalid or the update fails.

Example​

// 1. Get the current model
const printProduct = editor.getCurrentDesignPrintProductModel();

// 2. Perform advanced modifications (e.g., update text of a deeply nested item)
const targetItem = printProduct.surfaces.get(0).containers.get(1).items.get(6);
if (targetItem && 'text' in targetItem) {
  targetItem.text = '<p><span>Updated via Print Product Model!</span></p>';
}

// 3. Apply the modified model back to the editor
editor.setCurrentDesignPrintProductModel(printProduct);

setCurrentDesignVariant()​

setCurrentDesignVariant(id): Promise<DesignVariant>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:241

Sets the design variant by its ID

Parameters​

id​

string

The design variant ID

Returns​

Promise<DesignVariant>

The selected design variant

Throws​

If the design variant is not found

Example​

const designVariant = await editor.setCurrentDesignVariant("design-id-123");

setCurrentSurface()​

setCurrentSurface(options): Promise<Surface>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:269

Sets the current surface by index, ID, or name

Parameters​

options​

ISurfaceOptions

Surface selection options (surfaceIndex, surfaceId, or surfaceName)

Returns​

Promise<Surface>

The selected surface

Throws​

If the surface is not found

Example​

const surface = await editor.setCurrentSurface({ surfaceIndex: 0 });
// or
const surface = await editor.setCurrentSurface({ surfaceId: "surface-1" });
// or
const surface = await editor.setCurrentSurface({ surfaceName: "Front" });

setImagePlaceholderContentByAssetId()​

setImagePlaceholderContentByAssetId(targetItemId, assetId): Promise<void>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:530

Sets the image content for a specific image placeholder using an asset ID from the asset storage.

Parameters​

targetItemId​

string

The ID of the image placeholder to update.

assetId​

string

The ID of the image asset from the asset storage.

Returns​

Promise<void>

A promise that resolves when the image has been successfully applied.

Throws​

If the placeholder is not found, the asset is invalid, or an error occurs during the update.

Example​

// Get image placeholders
const placeholders = editor.getCurrentSurfaceImagePlaceholderItems();
const mainImagePlaceholder = placeholders.find(p => p.name === "MainImage");

if (mainImagePlaceholder) {
  // Get allowed images for this placeholder
  const allowedImages = await editor.getImagePlaceholderAllowedImages(mainImagePlaceholder, true, 0, 10);

  if (allowedImages.length > 0) {
    // Apply the first allowed image to the placeholder
    await editor.setImagePlaceholderContentByAssetId(mainImagePlaceholder.id, allowedImages[0].id);
  }
}

setLoadingState()​

setLoadingState(params): void

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:228

Manually sets the loading status

Parameters​

params​

ISetLoadingStateParams

Returns​

void

Example​

editor.setLoadingState({ state: LoadingState.LOADING, errorText: null });
editor.setLoadingState({ state: LoadingState.FAILED, errorText: "Loading error" });

setTextItemContent()​

setTextItemContent(targetItemId, content): Promise<void>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:504

Sets the text content for a specific text item on the current surface.

Parameters​

targetItemId​

string

The ID of the text item to update.

content​

string

The plain text content to set.

Returns​

Promise<void>

A promise that resolves when the content has been successfully applied.

Throws​

If the text item is not found or an error occurs during the update.

Example​

// Get all text items on the current surface
const textItems = editor.getCurrentSurfaceTextItems();
const titleItem = textItems.find(item => item.name === "Title");

if (titleItem) {
  // Set new text content
  await editor.setTextItemContent(titleItem.id, "New Title Text");
}

// Or update by ID directly
await editor.setTextItemContent("text-item-123", "Updated content");

setVariantById()​

setVariantById(id): Promise<ProductVariant>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:168

Sets the product variant by its ID

Parameters​

id​

number

The product variant ID

Returns​

Promise<ProductVariant>

The selected product variant

Throws​

If the variant is not found

Example​

const variant = await editor.setVariantById(67890);

setVariantBySku()​

setVariantBySku(sku): Promise<ProductVariant>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:194

Sets the product variant by its SKU

Parameters​

sku​

string

The product variant SKU

Returns​

Promise<ProductVariant>

The selected product variant

Throws​

If the variant is not found

Example​

const variant = await editor.setVariantBySku("SKU-12345");

setVariantByUid()​

setVariantByUid(uid): Promise<ProductVariant>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:181

Sets the product variant by its UID

Parameters​

uid​

string

The product variant UID

Returns​

Promise<ProductVariant>

The selected product variant

Throws​

If the variant is not found

Example​

const variant = await editor.setVariantByUid("variant-uid-123");

toggleLoadingState()​

toggleLoadingState(): void

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:216

Toggles the loading state (loading/loaded)

Returns​

void

Example​

editor.toggleLoadingState(); // Toggles between LOADING and LOADED

transformImagePlaceholderContent()​

transformImagePlaceholderContent(targetItemId, originalImage, cropperData): Promise<void>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:942

Applies a cropped or transformed image to a specific image placeholder.

Parameters​

targetItemId​

string

The ID of the image placeholder. Obtain it from getCurrentSurfaceImagePlaceholderItems().

originalImage​

File | Blob

The source image as a File (from file input) or Blob.

cropperData​

CropperData

Transformation data describing the crop region and scale to apply.

Returns​

Promise<void>

A promise that resolves when the transformed image has been applied.

Remarks​

This method is designed for advanced image manipulation workflows where the customer crops or otherwise transforms an image before applying it to a placeholder.

CRITICAL: Aspect Ratio Validation The aspect ratio of cropperData.frameSize MUST exactly match the aspect ratio of the target placeholder's frame. If the aspect ratios differ, the scaling calculation (which is based on width) will result in unexpected visual distortion or misalignment, as the height will be ignored.

To guarantee a valid aspect ratio, it is highly recommended to generate the initial crop data using the editor.getFitCropperData() utility method.

Throws​

If the placeholder is not found, the aspect ratio of cropperData does not match the placeholder, or an error occurs during transformation.

Example​

// Assume `cropper` is an instance of your image cropper UI component
const placeholders = editor.getCurrentSurfaceImagePlaceholderItems();
const mainImage = placeholders.find(p => p.name === "MainImage");

if (mainImage && cropper.hasImage()) {
  const originalImage = cropper.getSourceImage(); // File or Blob
  const cropperData = cropper.getCropData();      // CropperData from your UI

  await editor.transformImagePlaceholderContent(
    mainImage.id,
    originalImage,
    cropperData
  );
}

update()​

update(configuration): void

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:90

Updates editor resources or settings without full reinitialization

Parameters​

configuration​

IHeadlessEditorInitArgs

Updated configuration (only resources or settings)

Returns​

void

Example​

editor.update({ resources: { fonts: [...] } });

Overrides​

IWorkflowElement.update

uploadImagePlaceholderContent()​

uploadImagePlaceholderContent(targetItemId, file): Promise<void>

Defined in: workflow-elements/headless-editor/app/interfaces/configuration.interface.d.ts:568

Uploads a file and sets it as the content for a specific image placeholder.

Parameters​

targetItemId​

string

The ID of the image placeholder to update.

file​

File

The file to upload and apply.

Returns​

Promise<void>

A promise that resolves when the file has been uploaded and applied successfully.

Throws​

If the placeholder is not found, the file is invalid, or an error occurs during upload or application.

Example​

// Example 1: Upload from file input
const fileInput = document.getElementById('imageUpload') as HTMLInputElement;
const file = fileInput.files[0];

if (file) {
  const placeholders = editor.getCurrentSurfaceImagePlaceholderItems();
  const placeholder = placeholders.find(p => p.name === "UserPhoto");

  if (placeholder) {
    await editor.uploadImagePlaceholderContent(placeholder.id, file);
  }
}

// Example 2: Upload from drag-and-drop
document.addEventListener('drop', async (event) => {
  event.preventDefault();
  const file = event.dataTransfer.files[0];

  const placeholders = editor.getCurrentSurfaceImagePlaceholderItems();
  const placeholder = placeholders[0]; // Get first placeholder

  if (placeholder && file) {
    await editor.uploadImagePlaceholderContent(placeholder.id, file);
  }
});
Was this page helpful?