---
title: "Viewer settings and appearance | Customer's Canvas Hub"
canonical: "https://customerscanvas.com/docs/hub/dev-center/frontend-integration/workflow-elements/headless-editor/viewer-settings/"
---

# Viewer settings and appearance

> The Headless Editor ships a built-in design viewer with a minimal set of states: pre-initialization, loading, loaded, and failed. This page explains how to enable the viewer states and style them, and how to control the editor loading state from your host application. For the full settings list, see [Settings](https://customerscanvas.com/docs/hub/dev-center/frontend-integration/workflow-elements/headless-editor/settings.md).

## Enable the viewer

The viewer is controlled by the `viewer` settings block. It is disabled by default, so the editor adds no visible overlay to your page.

```typescript
await editor.init({
  configVersion: 2,
  input: { productReferenceId: "<product_reference_id>" },
  integration: { /* ... */ },
  settings: {
    viewer: {
      enabled: true,
      itemManipulationEnabled: true,
    },
  },
});
```

- `viewer.enabled` turns the viewer on or off. Disable it to keep the editor fully headless.
- `viewer.itemManipulationEnabled` allows the viewer to expose design item manipulation, such as selecting items on the canvas.

## Enable the viewer states

The viewer can show a pre-initialization, loading, and failure overlay. Configure each state with the `viewerStates` settings block.

```typescript
settings: {
  viewerStates: {
    preInitEnabled: true,
    loadingEnabled: true,
    failedEnabled: true,
  },
},
```

Use these states to give the customer visual feedback while the editor loads a product or recovers from an error.

## Style the viewer states

The viewer states are styled with CSS variables that follow the `--au-vs-` prefix. Override them in your page CSS to match your storefront. For example, to use custom colors for the failure state:

```css
au-headless-editor {
  --au-vs-failed-background: #fff4f2;
  --au-vs-failed-text-color: #b42318;
}
```

Scope the variables to `au-headless-editor` to affect only that editor instance, or set them on `:root` to apply them globally. See [CSS variables](https://customerscanvas.com/docs/hub/dev-center/frontend-integration/workflow-elements/headless-editor/css-variables.md) for the full list of variables and their defaults.

## Change settings after initialization

Call `update()` to change the viewer settings without reinitializing the editor.

```typescript
editor.update({
  settings: {
    viewer: {
      itemManipulationEnabled: false,
    },
  },
});
```

The change applies to the running editor instance.

## Control the loading state programmatically

When the built-in loading overlay does not fit your flow, drive your own loading indicator through the editor loading state API.

### Toggle the loading state

Call `toggleLoadingState()` to flip the editor between loading and loaded.

```typescript
editor.toggleLoadingState();
```

### Set the loading state explicitly

Call `setLoadingState()` to set a specific state and, for failures, an error message.

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

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

The `state` is one of the `LoadingState` values: `IDLE`, `LOADING`, `LOADED`, or `FAILED`. Pass `errorText` when you set the state to `FAILED`.

## Reference

- IHeadlessEditorSettings — the full settings shape.
- LoadingState — the loading states.
- ISetLoadingStateParams — the loading state parameters.
- IHeadlessEditor — the component method reference.