Configurator Core Events

Why Type-Safe Events?

Standard JavaScript event subscriptions use string names. A misspelled event name won't produce any error -- the browser simply never fires a callback for a name that doesn't exist, and there is no way to know.

The Epigraph Configurator solves this by storing all event names in an EVENTS object on the Core API. If you try to access an event that doesn't exist, you get a TypeError immediately instead of a silent failure.

// Fragile -- a typo here fails silently
configurator.addEventListener("contxtMenu:show", callback);

// Type-safe -- a typo here throws a TypeError
configurator.addEventListener(coreApi.EVENTS.UI.ContxtMenu_Show, callback);
// → TypeError: Cannot read properties of undefined

Accessing Events

All events are accessed via coreApi.EVENTS.<category>.<eventName>:

const configurator = document.getElementById("wcEpigraphConfigurator");

configurator.addEventListener("coreApi:ready", () => {
  const coreApi = configurator.api.core;

  configurator.addEventListener(
    coreApi.EVENTS.SCENE.Item_Added,
    () => {
      console.log("An item was added to the scene");
    }
  );
});

Note: The coreApi:ready and coreApi:failed lifecycle events are not part of the EVENTS object. These two events must always be subscribed to using string names, since the Core API (and therefore the EVENTS object) is not yet available when you need to listen for them.

Lifecycle Events

These events are subscribed to directly with string names on the web component element:

configurator.addEventListener("coreApi:ready", () => {
  // Core API is available at configurator.api.core
});

configurator.addEventListener("coreApi:failed", (event) => {
  // Show error UI to the user
});

UI Events

Events related to the configurator's user interface elements. Access via coreApi.EVENTS.UI.*.

Example: Custom Context Menu

configurator.addEventListener(
  coreApi.EVENTS.UI.ContextMenu_Show,
  (event) => {
    const item = event.data.primary;
    console.log(`Clicked: ${item.name} (${item.guid})`);
    console.log("Available looks:", item.data.itemData.looks);
    // Show your custom context menu
  }
);

configurator.addEventListener(
  coreApi.EVENTS.UI.ContextMenu_Hide,
  () => {
    // Hide your custom context menu
  }
);

Scene Events

Events related to changes in the 3D scene. Access via coreApi.EVENTS.SCENE.*.

Example: Reacting to Scene Changes

configurator.addEventListener(
  coreApi.EVENTS.SCENE.Item_Added,
  () => {
    console.log("Item count:", coreApi.getSceneItemCount());
  }
);

configurator.addEventListener(
  coreApi.EVENTS.SCENE.CartItems_Updated,
  async () => {
    const cartItems = await coreApi.getCartItemsAsync();
    // Update your cart UI
  }
);

configurator.addEventListener(
  coreApi.EVENTS.SCENE.SavedConfiguration_Loaded,
  () => {
    console.log("Configuration loaded successfully");
  }
);

Configuration Events

Events related to item interaction and camera state. Access via coreApi.EVENTS.CONFIGURATION.*.

Quick Reference

All events at a glance:

EVENTS
├── UI
│   ├── PreloadScreen_Show
│   ├── PreloadScreen_Hide
│   ├── ContextMenu_Show
│   ├── ContextMenu_Hide
│   ├── ContextMenu_InfoBtnClicked
│   ├── UtilityMenu_Show
│   ├── UtilityMenu_Hide
│   ├── ShareButton_Show
│   ├── ShareButton_Hide
│   ├── ViewInYourSpaceButton_Show
│   ├── ViewInYourSpaceButton_Hide
│   ├── ResetButton_Show
│   ├── ResetButton_Hide
│   ├── DimensionsButton_Show
│   ├── DimensionsButton_Hide
│   ├── Instructions_Show
│   ├── ReviewCart_Shown
│   └── ReviewCart_Hidden
├── SCENE
│   ├── Item_Added
│   ├── Item_Removed
│   ├── Items_Updated
│   ├── FittingSkuIds_Updated
│   ├── CartItems_Updated
│   ├── Hotspot_Enter
│   ├── Hotspot_Exit
│   ├── SavedConfiguration_Loaded
│   ├── MaterialOverrides_Exists
│   ├── Cart_Checkout
│   ├── Cart_OutOfStock
│   ├── Cart_StatusUpdated
│   ├── ReplaceableCategory_Updated
│   ├── GlobalVariant_Updated
│   ├── CategoryData_Updated
│   ├── GlobalGeometryVariant_Updated
│   ├── Ghost_Loaded
│   ├── Model_Loaded
│   ├── Model_Removed
│   ├── Scene_Cleared
│   ├── Inventory_Updated
│   ├── DraggingOnDrop_CollisionDetected
│   ├── ItemRemoveModalTriggered
│   ├── ActionButton_Clicked
│   └── CartMessage_Update
└── CONFIGURATION
    ├── OnClickItem
    └── CameraDetails_Update

Preload Events

These string-based events track asset loading progress. They are useful if you want to build a custom loading indicator.

configurator.addEventListener("preload:update", (event) => {
  console.log(`Loading: ${event.progress}%`);
});

Further Reading

• API Reference -- Full method and property reference for the Core API
• Building a Custom UI -- Headless mode setup and basic API usage
• Implementing Drag and Drop -- Drag-and-drop with custom context menu events