---
title: "Products, options, and variants | Customer's Canvas Hub"
canonical: "https://customerscanvas.com/docs/hub/dev-center/frontend-integration/workflow-elements/headless-editor/products-options-variants/"
---

# 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.

```typescript
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.

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

The returned `Product` contains the product metadata and its options. See [Integration guidelines](https://customerscanvas.com/docs/hub/dev-center/frontend-integration/workflow-elements/headless-editor/integration-guidelines.md) for the full initialization and restore scenarios.

## Read the current product

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

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
const variant = await editor.setVariantById(67890);
```

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

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

Read the current variant with `getCurrentVariant()`.

```typescript
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](https://customerscanvas.com/docs/hub/dev-center/concepts/pim.md#design-variant).

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

   ```typescript
   const variant = editor.getCurrentVariant();

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

2. Select one by its ID.

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

3. Read the current design variant.

   ```typescript
   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

```typescript
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.

```typescript
const surface = await editor.setCurrentSurface({ surfaceIndex: 0 });
```

```typescript
const surface = await editor.setCurrentSurface({ surfaceId: "surface-1" });
```

```typescript
const surface = await editor.setCurrentSurface({ surfaceName: "Front" });
```

### Read the current surface

```typescript
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

- Product — the product model.
- ProductVariant — the product variant model.
- DesignVariant — the design variant model.
- Surface — the surface model.
- OpenProductInput — the accepted product inputs.
- IHeadlessEditor — the full method reference.