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.

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-app-template-error	AppTemplateErrorEventPayload	Error loading embed template
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-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-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

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

Related

• 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