---
title: "Design elements | Customer's Canvas Hub"
canonical: "https://customerscanvas.com/docs/hub/dev-center/frontend-integration/workflow-elements/headless-editor/design-elements/"
---

# Design elements

> Read the text items, image placeholders, and barcodes on the current design surface, and update them from your host application. Each element list can be narrowed to a specific container. You can also change the container settings of the surface and manipulate the underlying print product model.

## Text items

Text items are the text elements defined in the design data schema. Each item carries the current value, its length limits, and a schema definition with the label, description, prompt, and constraints.

### List text items

Call `getCurrentSurfaceTextItems()` to get the text items of the active surface.

```typescript
const textItems = editor.getCurrentSurfaceTextItems();

for (const item of textItems) {
  console.log(item.id, item.name, item.value);
}
```

Pass `{ containerId }` to narrow the result to a specific container.

```typescript
const containerItems = editor.getCurrentSurfaceTextItems({
  containerId: "<container_id>",
});
```

Each `TextItem` exposes an `id`, a `name`, the current `value`, the `lengthLimits`, and a `schemaDefinition` with `displayName`, `description`, `required`, `constraints`, and `prompt`. Use `schemaDefinition` to render the label and placeholder of your input control rather than relying on the internal item name.

### Set text content

Call `setTextItemContent()` to update a text item by its ID.

```typescript
const titleItem = textItems.find(item => item.name === "Title");

if (titleItem) {
  await editor.setTextItemContent(titleItem.id, "New Title Text");
}
```

The second argument is the plain text content to apply. The method resolves when the content has been applied.

## Image placeholders

Image placeholders are the image elements defined in the design data schema. Each placeholder exposes its schema and supports applying an image from the asset library or an uploaded file.

### List image placeholders

Call `getCurrentSurfaceImagePlaceholderItems()` to get the image placeholders of the active surface.

```typescript
const placeholders = editor.getCurrentSurfaceImagePlaceholderItems();

for (const placeholder of placeholders) {
  console.log(placeholder.id, placeholder.name);
}
```

Each `PlaceholderItem` exposes an `id`, a `name`, a `subfolder`, the `contentManipulation`, `showSelectButton`, and `allowFolder` flags, and a `schemaDefinition` with the same `displayName`, `description`, `required`, `constraints`, and `prompt` shape as text items.

Pass `{ containerId }` to narrow the result to a specific container.

```typescript
const containerPlaceholders = editor.getCurrentSurfaceImagePlaceholderItems({
  containerId: "<container_id>",
});
```

### List allowed images

Call `getImagePlaceholderAllowedImages()` to fetch the images that can be applied to a placeholder.

```typescript
const mainImage = placeholders.find(p => p.name === "MainImage");

if (mainImage) {
  const images = await editor.getImagePlaceholderAllowedImages(
    mainImage,
    true, // include subfolders
    0,    // skip
    10,   // take
  );

  for (const image of images) {
    console.log(image.id, image.name);
  }
}
```

The last three arguments are optional. Set `includeSubfolders` to `true` to include nested subfolders. Use `skip` and `take` to page through the results.

### Set an image by asset ID

Call `setImagePlaceholderContentByAssetId()` to apply a library image to a placeholder.

```typescript
const images = await editor.getImagePlaceholderAllowedImages(mainImage);

if (images.length > 0) {
  await editor.setImagePlaceholderContentByAssetId(mainImage.id, images[0].id);
}
```

### Upload an image

Call `uploadImagePlaceholderContent()` to upload a file and apply it to a placeholder.

```typescript
const fileInput = document.querySelector("input[type='file']") as HTMLInputElement;
const file = fileInput.files?.[0];

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

The method accepts the target placeholder ID and a browser `File`.

### Reset placeholder content

Call `resetImagePlaceholderContent()` to clear the image content of a placeholder.

```typescript
const mainImage = placeholders.find(p => p.name === "MainImage");

if (mainImage) {
  await editor.resetImagePlaceholderContent(mainImage.id);
}
```

## Barcodes and QR codes

Barcode items are the barcode and QR code elements defined in the design data schema. Each item describes its subtype, its format, and a data payload whose shape depends on the subtype.

### List barcode items

Call `getCurrentSurfaceBarcodeItems()` to get the barcode and QR code items of the active surface.

```typescript
const barcodeItems = editor.getCurrentSurfaceBarcodeItems();

for (const item of barcodeItems) {
  console.log(item.id, item.name, item.subType, item.format);
}
```

Each `IBarcodeItem` exposes an `id`, a `name`, a `subType`, a `format`, and a `data` payload. The `subType` is one of the `BarcodeSubType` values, and `format` is one of the `BarcodeFormat` values.

Pass `{ containerId }` to narrow the result to a specific container.

```typescript
const containerItems = editor.getCurrentSurfaceBarcodeItems({
  containerId: "<container_id>",
});
```

### Set a URL QR code

Call `setBarcodeItemContent()` to update a barcode item by its ID. For a URL QR code, pass `BarcodeSubType.URL`, `BarcodeFormat.QR_CODE`, and a data object with a `value`.

```typescript
import { BarcodeFormat, BarcodeSubType } from "@aurigma/workflow-elements/headless-editor";

const urlQr = barcodeItems.find(item => item.name === "WebsiteQR");

if (urlQr) {
  editor.setBarcodeItemContent(
    urlQr.id,
    BarcodeSubType.URL,
    BarcodeFormat.QR_CODE,
    { value: "https://example.com" },
  );
}
```

### Set a vCard QR code

For a contact QR code, pass `BarcodeSubType.V_CARD` with `BarcodeFormat.QR_CODE` and a vCard data object.

```typescript
const contactQr = barcodeItems.find(item => item.name === "ContactQR");

if (contactQr) {
  editor.setBarcodeItemContent(
    contactQr.id,
    BarcodeSubType.V_CARD,
    BarcodeFormat.QR_CODE,
    {
      firstName: "Jane",
      lastName: "Doe",
      organization: "Aurigma",
      email: "jane.doe@example.com",
      mobilePhone: "04805718146",
      url: "https://customerscanvashub.com",
    },
  );
}
```

The vCard shape supports `firstName`, `lastName`, `organization`, `position`, `email`, `mobilePhone`, `fax`, `phone`, `url`, and an `addresses` list. For other barcode formats, pass a `value` string and the matching `BarcodeFormat`, such as `BarcodeFormat.EAN_13`.

## Containers

A container is a named group of design elements on a surface. The `Container` model exposes the container name, type, visibility, and visualization settings, as well as the optional color limits (`maxColorNumber`, `paletteUId`).

### Read the container settings

Call `getCurrentSurfaceContainerSettings()` to get the container settings of the current surface.

```typescript
const container = editor.getCurrentSurfaceContainerSettings();
console.log(container);
```

### Update the container settings

Call `updateCurrentSurfaceContainerSettings()` to apply the updated settings to the current surface. Obtain the container from `getCurrentSurfaceContainerSettings()`, modify it, and pass it back. The method accepts a partial container, so you can pass only the fields you want to change.

For example, this is how you can switch the container to the colorless type and apply a texture visualization to it:

```typescript
const container = editor.getCurrentSurfaceContainerSettings();

container.type = "Colorless";
container.visible = true;
container.visualization = {
  type: "TextureVisualization",
  opacity: 0,
  enableGlareEffect: false,
  textureName: "texture_2x2",
  textureSource: {
    id: "66def9be3e121d0c93632bbf",
    width: 2480,
    height: 3508,
    pageIndex: 0
  },
  color: null
};

await editor.updateCurrentSurfaceContainerSettings(container);
```

The `type` is one of the `ContainerType` values, and the `visualization` object combines the color and texture visualization settings, such as the opacity and the glare effect.

## Print product model

For low-level manipulations, the editor exposes the print product model of the current design — the `PrintProduct` from the `@aurigma/design-atoms-model` library.

### Read the print product model

Call `getCurrentDesignPrintProductModel()` to get the model.

```typescript
const printProduct = editor.getCurrentDesignPrintProductModel();
console.log(printProduct);
```

### Apply changes to the print product model

Modify the model and pass it to `setCurrentDesignPrintProductModel()` to apply the changes to the design.

```typescript
const printProduct = editor.getCurrentDesignPrintProductModel();

printProduct.surfaces.get(0).containers.get(1).items.get(6).text = "<p><span>HI!</span></p>";

editor.setCurrentDesignPrintProductModel(printProduct);
```

## Reference

- TextItem — the text item model.
- SchemaDefinition — the schema metadata shared by design elements.
- PlaceholderItem — the image placeholder model.
- IPlaceholderOptions — the placeholder filtering options.
- IBarcodeItem — the barcode item model.
- IBarcodeVCardData — the vCard data model.
- BarcodeSubType and BarcodeFormat — the supported subtypes and formats.
- Container — the container model.
- ContainerType — the container type values.
- IHeadlessEditor — the full method reference.