Skip to main content

Products, options, and variants

Drive product selection, option choices, and design variant switching from your host application. The Headless Editor exposes methods to load products, query and change options, switch variants, and move between design surfaces.

Open a product​

Call openProduct() to load another product after initialization without a full reinitialization. The editor accepts either the Customer's Canvas product ID or a product reference.

import type { OpenProductInput } from "@aurigma/workflow-elements/headless-editor";

const input: OpenProductInput = { productId: 12345 };

const product = await editor.openProduct(input);

Open a product by its external product reference instead.

const product = await editor.openProduct({ productReferenceId: "external-ref-123" });

The returned Product contains the product metadata and its options. See Integration guidelines for the full initialization and restore scenarios.

Read the current product​

Call getCurrentProduct() to read the product that is currently loaded.

const product = editor.getCurrentProduct();

console.log(product.productId);
console.log(product.name);

for (const option of product.options) {
  console.log(option.name);
}

The Product exposes its options through options, and each Option exposes its available values.

Work with options and choices​

Product options are the selectable attributes of the product, such as color or size. Each option has its own list of values. The currently selected values across all options are called choices.

Read the current choices​

Call getChoices() to get the selected option values by option ID.

const choices = editor.getChoices();

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

Call getChoicesValues() to get the same selection as option names and values for display.

const values = editor.getChoicesValues();

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

Set the choices​

Call setChoices() to select option values and get the product variant that matches the selection.

import type { Choice } from "@aurigma/workflow-elements/headless-editor";

const choices: Choice<string | string[]> = {
  "1": "101",           // option ID 1, value ID "101"
  "2": ["201", "202"],  // option ID 2, a list of value IDs
};

const variant = await editor.setChoices(choices);

The method returns the matching ProductVariant, or throws a HeadlessEditorError when no variant matches the given combination. The editor emits variantchanged after the variant is applied.

important

Subscribe to optionchoiceschanged before calling setChoices() to update the displayed choice selection when the editor normalizes or changes the values.

Select a product variant​

A product variant is a concrete combination of option values. Select a variant directly by ID, UID, or SKU.

const variant = await editor.setVariantById(67890);
const variant = await editor.setVariantByUid("variant-uid-123");
const variant = await editor.setVariantBySku("SKU-12345");

Read the current variant with getCurrentVariant().

const variant = editor.getCurrentVariant();

console.log(variant.sku);
console.log(variant.price);

The ProductVariant exposes its identifier, UID, SKU, storefront product variant ID, price, availability, and the list of available designVariants.

Switch a design variant​

A design variant is the initial design for one customization path of a product variant. Each product variant can offer several design variants, typically one per design group. For background, see Design variants and design groups.

  1. Get the available design variants from the current product variant.

    const variant = editor.getCurrentVariant();

    for (const designVariant of variant.designVariants) {
      console.log(designVariant.id, designVariant.designName);
    }

  2. Select one by its ID.

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

  3. Read the current design variant.

    const current = editor.getCurrentDesignVariant();

    console.log(current.id);

The editor emits variantchanged when the product variant changes and designvariantchanged when the design variant changes. The currently listed design elements always belong to the active design variant.

Work with design surfaces​

A design surface represents one printable side of a product, such as the front or the back of a T-shirt. Read the surfaces of the current design to build a surface selector.

List surfaces​

const surfaces = editor.getCurrentSurfaces();

for (const surface of surfaces) {
  console.log(surface.id, surface.name);
}

Select a surface​

Call setCurrentSurface() with the surface index, ID, or name.

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

Read the current surface​

const surface = editor.getCurrentSurface();

console.log(surface.name);

The design element methods, such as getCurrentSurfaceTextItems(), operate on the active surface. After switching surfaces, the editor emits surfacechanged; rebuild the element controls in response.

Reference​

Last updated on
Was this page helpful?