Skip to main content

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.

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.

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.

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:

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 for the full list of variables and their defaults.

Change settings after initialization​

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

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.

editor.toggleLoadingState();

Set the loading state explicitly​

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

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​

Last updated on
Was this page helpful?