Events

Mimeeq dispatches browser events to notify your code about state changes and user interactions inside the configurator. All events are standard DOM CustomEvent objects dispatched on document, with payload data available through event.detail.

document.addEventListener('mimeeq-select-option', (event) => {
  const { variantCode, groupName, option } = event.detail;
  console.log(`Option "${option.name}" selected in "${groupName}"`);
});

Events also propagate to the parent frame via window.parent.postMessage, so integrations running the configurator inside an <iframe> can listen for them without direct DOM access.

For how events fit alongside observers, the REST API, and webhooks, see the Architecture Overview.

tip

All event payload types are available as TypeScript interfaces. See the MimeeqEventMap type for a complete mapping of event names to their payload types, which enables fully type-safe event listeners.

Standard Product Lifecycle

The diagram below shows the full event sequence for a standard product, from page load to cart. Each event links to its category page for payload details and code examples.

  Page loads <mmq-embed>
       │
       ▼
  mimeeq-app-loaded                    ← API ready, safe to subscribe to observers
       │
       ▼
  mimeeq-3d-product-initialized        ← 3D scene rendered, product interactive
       │
       ▼
  ┌──────────────────────────────────────────────────┐
  │  Configuration loop (repeats per user action)    │
  │                                                  │
  │  mimeeq-select-option                            │
  │       │                                          │
  │       ├── if price-affecting ► mimeeq-price-change
  │       │                            │             │
  │       │                            ▼             │
  │       │                     pricing observer     │
  │       │                     updates              │
  │       │                                          │
  │       └── 3D/2D scene updates in parallel        │
  │                                                  │
  │  (history events may fire on undo/redo/reset)    │
  └──────────────────────────────────────────────────┘
       │
       ▼
  User clicks the primary action button
       │
       ├── validation fails ──► toast error, NO event fires
       │
       ├── variant="basket" ──► mimeeq-add-to-cart
       │                        (image, shortCode, price, currency)
       │
       └── variant="default" ─► mimeeq-show-summary
                                (no image, shortCode, or price)
       │
       ▼
  mimeeq-leave-configurator            ← user navigates away or embed unmounts

For the modular product equivalent, see Modular Events.

Event Categories

Events are documented by flow — grouped around the workflows they belong to, so you can see what fires in sequence and how events relate to each other.

Category	What it covers
Lifecycle Events	Load → initialization → teardown. The events that tell you when the configurator is ready and when it's gone.
Configuration Events	Option selection, price changes, tab switching, history navigation, 3D mesh interaction, and other events fired during standard product configuration.
Modular Events	Scene composition, product manipulation, option selection, scene management, and UI state changes specific to the modular configurator.
Finish & Cart Events	The branching flow when the user finishes configuring: summary, product selection, or add-to-cart — depending on embed variant and basket mode.
Basket Events	Mimeeq's built-in B2B cart lifecycle: creation, item management, price updates, and order submission.
Authentication Events	Login, logout, signup, password reset, and profile events from the Mimeeq authentication system.
Media & Export Events	PDF generation, image/scene export, AR code generation, and file downloads.
Product List Events	Product browsing, selection, and favourites management within the product list embed.
Host-Triggered Events	Events that your code dispatches into the configurator to control visibility, loaders, and basket UI.
Error Events	Failures during template, config, or observer API data loading.

Quick Reference

The table below lists every public event for fast lookup. Click through to the category page for full descriptions, payload details, and code examples.

Lifecycle

Event	Payload	Description
`mimeeq-app-loaded`	—	Configurator library loaded and ready
`mimeeq-3d-product-initialized`	—	3D product fully initialized
`mimeeq-2d-product-initialized`	—	2D product fully loaded, all image layers ready
`mimeeq-webgl-not-supported`	—	WebGL not available, 3D product cannot render
`mimeeq-product-list-initialized`	—	Product list loaded from database
`mimeeq-embed-unmounted`	—	Web component removed from DOM

Configuration

Event	Payload	Description
`mimeeq-enter-product`	`{ prefix }`	Product configurator opened
`mimeeq-leave-product`	`{ prefix }`	Product configurator closed
`mimeeq-select-option`	`SelectOptionEventPayload`	Option selected in option panel
`mimeeq-select-popular-variant`	`SelectPopularVariantEventPayload`	Popular configuration selected
`mimeeq-select-tab`	`SelectTabEventPayload`	Tab changed
`mimeeq-price-change`	`PriceChangeEventPayload`	About to fetch updated price (standard only)
`mimeeq-select-filters`	`SelectFiltersEventPayload`	Filters changed
`mimeeq-deactivate-matching-options`	`DeactivateMatchingOptionsEventPayload`	Match Options toggled (deactivated)
`mimeeq-activate-matching-options`	`DeactivateMatchingOptionsEventPayload`	Match Options toggled (activated)
`mimeeq-change-quantity`	`ChangeQuantityEventPayload`	Quantity changed
`mimeeq-clear-filters`	—	Filters cleared
`mimeeq-download-file`	`DownloadFileEventPayload`	File downloaded
`mimeeq-3d-show-dimensions`	—	Dimensions overlay shown
`mimeeq-3d-hide-dimensions`	—	Dimensions overlay hidden
`mimeeq-3d-zoom-out-scene`	—	Zoom Out button clicked
`mimeeq-open-related-product`	`OpenRelatedProductEventPayload`	Related product clicked
`mimeeq-click-hotspot`	`ClickHotspotEventPayload`	Hotspot clicked in 3D scene
`mimeeq-history-go-back`	`HistoryItem`	History undo
`mimeeq-history-go-forward`	`HistoryItem`	History redo
`mimeeq-history-reset`	—	History reset
`mimeeq-configurator-go-back`	—	Back arrow clicked
`mimeeq-configurator-clear-history`	—	Close in modal mode
`mimeeq-3d-open-full-screen`	—	Entered fullscreen
`mimeeq-3d-close-full-screen`	—	Left fullscreen
`mmq-action-highlight-group-on`	`string`	Hover mesh with Highlight Group
`mmq-action-highlight-group-off`	`string`	Left hover on Highlight Group mesh
`mmq-action-open-group`	`string`	Clicked mesh with Open Group
`mmq-action-scroll-to-block`	`string`	Clicked mesh with Scroll to Block
`mmq-action-flash-highlight-block`	`string`	Scrolled to option block after Scroll to Block
`mimeeq-open-option-panel`	—	Option block group (accordion) opened
`mimeeq-app-url-change`	`FinishEventPayload`	URL state changed (option selection, history, related product, finish)

Modular

Event	Payload	Description
`mimeeq-modular-enter-product`	—	Modular product entered
`mimeeq-modular-leave-product`	—	Modular product left
`mimeeq-modular-select-option`	`ModularSelectOptionEventPayload`	Option selected (single product)
`mimeeq-modular-select-option-multiple`	`ModularSelectOptionMultipleEventPayload`	Option applied to multiple products
`mimeeq-modular-add-product-to-scene`	`ModularProductSceneEventPayload`	Product added to scene
`mimeeq-modular-insert-product-to-scene`	`ModularProductSceneEventPayload`	Product inserted between elements
`mimeeq-modular-move-product`	`ModularProductSceneEventPayload`	Product moved on scene
`mimeeq-modular-product-replaced`	`ModularProductSceneEventPayload`	Product replaced on scene
`mimeeq-modular-clone-product`	—	Product cloned
`mimeeq-modular-remove-product`	—	Product removed
`mimeeq-modular-select-product-to-add`	`ModularSelectProductToAddEventPayload`	Product chosen from add list
`mimeeq-modular-clear-scene`	—	Scene cleared
`mimeeq-modular-flip-product`	—	Product flipped
`mimeeq-modular-load-scene`	`ModularLoadSceneEventPayload`	Scene loaded
`mimeeq-modular-load-scene-success`	—	Scene load completed
`mimeeq-modular-save-scene`	`ModularSaveSceneEventPayload`	Scene saved as favourite
`mimeeq-modular-create-new-scene`	`ModularLoadSceneEventPayload`	New scene short code assigned
`mimeeq-modular-open-my-scenes`	—	My Scenes opened
`mimeeq-modular-close-my-scenes`	—	My Scenes closed
`mimeeq-modular-close-select-scene-modal`	—	Load Scene modal closed
`mimeeq-modular-open-summary`	—	Finish clicked (summary opened)
`mimeeq-modular-close-summary`	—	Summary closed
`mimeeq-modular-open-warning`	—	Required-snap validation warning opened
`mimeeq-modular-close-warning`	—	Warning modal closed
`mimeeq-modular-set-clone`	—	Clone action activated
`mimeeq-modular-set-move`	—	Move action activated
`mimeeq-modular-set-copy-styles`	—	Copy Styles action activated
`mimeeq-modular-set-slide`	—	Slide action activated
`mimeeq-modular-set-replace`	—	Replace action activated
`mimeeq-modular-show-grid`	—	Grid activated
`mimeeq-modular-hide-grid`	—	Grid hidden
`mimeeq-modular-unselect-all`	—	All products deselected
`mimeeq-modular-abort-action`	—	Active action aborted
`mimeeq-modular-history-go-back`	—	Modular history undo
`mimeeq-modular-history-go-forward`	—	Modular history redo
`mmq-webgl-support-modal-close`	—	No WebGL support modal dismissed

Finish & Cart

Event	Payload	Description
`mimeeq-before-add-to-cart`	`BeforeAddToCartEventPayload`	Add to Cart action started, before validation
`mimeeq-show-summary`	`FinishEventPayload`	Finish button clicked
`mimeeq-select-product`	`FinishEventPayload`	Select button clicked (internal/quotation use only)
`mimeeq-add-to-cart`	`FinishEventPayload`	Add to Cart clicked (basket mode)

Basket

Event	Payload	Description
`mimeeq-basket-created`	`BasketCreatedEventPayload`	New basket created
`mimeeq-basket-item-added`	`BasketItemAddedEventPayload`	Item added to basket
`mimeeq-basket-updated`	`BasketUpdatedEventPayload`	Basket contents or totals updated
`mimeeq-basket-submitted`	`BasketSubmittedEventPayload`	Basket submitted as order/RFQ

Authentication

Event	Payload	Description
`mimeeq-auth-loaded`	—	Authentication library loaded
`mimeeq-enter-login`	—	Login form shown
`mimeeq-leave-login`	—	Login form closed
`mimeeq-login-success`	`LoginSuccessEventPayload`	Login successful
`mimeeq-enter-forgot-password`	—	Forgot Password opened
`mimeeq-leave-forgot-password`	—	Forgot Password closed
`mimeeq-enter-sign-up`	—	Sign Up form shown
`mimeeq-leave-sign-up`	—	Sign Up form closed
`mimeeq-sign-up-success`	`SignUpSuccessEventPayload`	Sign Up successful
`mimeeq-logout-success`	—	Logout completed
`mimeeq-user-signed-in`	`{ firstName, lastName, email }`	Session established after login
`mimeeq-user-signed-out`	—	Session destroyed
`mimeeq-user-updated`	—	User profile data updated
`mimeeq-user-deleted`	—	Customer partner user deleted own account
`mimeeq-resend-signup-confirm-code`	`{ email }`	Signup verification code resent
`mimeeq-enter-profile`	—	Profile opened
`mimeeq-leave-profile`	—	Profile closed
`mimeeq-login-closed`	—	Login modal dismissed
`mimeeq-profile-closed`	—	Profile modal dismissed
`mimeeq-forgot-password-closed`	—	Forgot Password modal dismissed
`mimeeq-select-company`	`SelectCompanyEventPayload`	Company changed in price selector
`mimeeq-select-price-type`	`SelectPriceTypeEventPayload`	Price type changed

Media & Export

Event	Payload	Description
`mimeeq-show-export-pdf-modal`	—	PDF export modal opened
`mimeeq-pdf-generate-start`	—	PDF generation started
`mimeeq-pdf-generate-done`	—	PDF generation completed
`mimeeq-3d-before-export-image`	—	Image export started
`mimeeq-3d-after-export-image`	—	Image exported and saved
`mimeeq-3d-before-export-scene`	—	3D model export started
`mimeeq-3d-after-export-scene`	—	3D model exported and saved
`mimeeq-generate-ar-short-code`	`GenerateArShortCodeEventPayload`	AR short code generated
`mimeeq-ar-get-back-to-configuration`	`ArGoBackEventPayload`	Edit clicked on AR page

Product List & Favourites

Event	Payload	Description
`mimeeq-product-list-initialized`	—	Product list loaded from database
`mimeeq-product-list-select-product`	`ProductListSelectProductEventPayload`	Product selected from list
`mimeeq-favourites-add-product`	`ProductPrefixEventPayload`	Product added to favourites
`mimeeq-favourites-remove-product`	`ProductPrefixEventPayload`	Product removed from favourites
`mimeeq-favourites-add-collection`	`FavouritesCollectionEventPayload`	Collection created
`mimeeq-favourites-update-collection`	`FavouritesCollectionEventPayload`	Collection updated
`mimeeq-favourites-remove-collection`	—	Collection(s) deleted
`mimeeq-favourites-copy-to-collection`	`FavouritesCollectionItemsEventPayload`	Items copied to collection
`mimeeq-favourites-move-to-collection`	`FavouritesCollectionItemsEventPayload`	Items moved to collection
`mimeeq-favourites-delete-from-collection`	`FavouritesDeleteFromCollectionEventPayload`	Items removed from collection
`mimeeq-open-favourites`	—	Favourites panel opened
`mimeeq-close-favourites`	—	Favourites panel closed
`mimeeq-select-favourites-collection`	`SelectFavouritesCollectionEventPayload`	Collection selected from menu

Errors

Event	Payload	Description
`mimeeq-app-template-error`	`AppTemplateErrorEventPayload`	Error loading embed template
`mimeeq-app-config-error`	`AppConfigErrorEventPayload`	Error loading JSON configuration (`embed_data` or `customers`)
`mimeeq-app-api-error`	`AppApiErrorEventPayload`	Internal API call failed

Host-Triggered Events

These events flow in the opposite direction — your code dispatches them to control the configurator.

Event	Description
`mimeeq-show-basket-loader`	Show loader on the action button next to the price
`mimeeq-hide-basket-loader`	Hide loader on the action button next to the price
`mimeeq-show-price-loader`	Show loader in price box
`mimeeq-hide-price-loader`	Hide loader in price box
`mimeeq-show-add-to-cart-toast`	Show "added to basket" confirmation toast
`mimeeq-hide-add-to-cart-toast`	Hide "added to basket" toast
`mimeeq-trigger-add-to-cart`	Trigger finish/add-to-cart action programmatically
`mimeeq-show-modular-summary`	Open modular summary screen
`mimeeq-refresh-translations`	Reload custom translations from `window.mimeeqCustomMessages`
`mimeeq-show-configurator`	Show hidden configurator (legacy embed only)
`mimeeq-show-modular`	Show hidden modular configurator (legacy embed only)
`mimeeq-unmount`	Remove all Mimeeq instances from DOM (legacy embed only)

Legacy Events

warning

The events below apply only to the legacy embed (non-web-component). They are deprecated and should not be used in new integrations. Use the web component embed and its events instead.

Event	Payload	Description	Replacement
`mimeeq-configurator-closed`	—	Configurator modal closed	`mimeeq-embed-unmounted`
`mimeeq-modular-closed`	—	Modular modal closed	`mimeeq-embed-unmounted`
`mimeeq-tree-unmounted`	`TreeUnmountedEventPayload`	Embed removed from DOM with type identifier	`mimeeq-embed-unmounted`
`mimeeq-show-configurator`	—	Show configurator when Render on Mount is disabled	`<mmq-embed>.show()`
`mimeeq-show-modular`	—	Show modular when Render on Mount is disabled	`<mmq-embed>.show()`
`mimeeq-unmount`	—	Remove all Mimeeq instances from DOM	Remove `<mmq-embed>` element

Ecommerce Integration — step-by-step guide for handling mimeeq-add-to-cart in your shopping cart
Google Analytics Integration — example of event-driven analytics tracking
Basket Embed — Mimeeq's built-in B2B cart with its own event lifecycle
MimeeqEventMap Type Reference — TypeScript event name → payload mapping
Using Events to Track Configurator Usage — business perspective on event tracking

Standard Product Lifecycle​

Event Categories​

Quick Reference​

Lifecycle​

Configuration​

Modular​

Finish & Cart​

Basket​

Authentication​

Media & Export​

Product List & Favourites​

Errors​

Host-Triggered Events​

Legacy Events​

Related​