Skip to main content

URL Navigation

The Mimeeq configurator can synchronize its internal state with the browser's URL. When enabled, every user action — selecting a product, changing a tab, opening AR view — is reflected as query parameters in the address bar. This makes configurations shareable via links, preservable across page refreshes, and compatible with browser back/forward navigation.

This guide explains how URL navigation works, how to enable it, what parameters appear in the URL, and how behavior differs across embed types.

Enabling URL Navigation​

URL navigation is controlled by a single flag called Use URL Navigation (property name withHistory). There are two ways to enable it:

Via Embed Template (recommended): In the Mimeeq admin panel, open your embed template's Settings section and enable Use URL navigation. This is the cleanest approach — no code changes needed.

Via HTML attribute: Set the with-history attribute directly on the web component:

<mmq-embed short-code="YOUR_SHORT_CODE" template="your_template" with-history></mmq-embed>

Either method produces the same result. If both are set, the attribute on the HTML element takes effect alongside the template setting — either one being true is enough to enable URL navigation.

note

Basket embeds (BASKET variant) always use URL navigation internally, regardless of the withHistory setting. This ensures cart reference codes and basket state are always URL-addressable.

How It Works​

The Two Modes​

The embed component maintains an internal record of the current navigation state — which product is displayed, which tab is active, whether the user is in AR mode, and so on. This state is stored as a QueryParams object.

When withHistory is disabled (the default), this state lives only in memory. The URL never changes. If the user refreshes the page, the configurator returns to its initial state. Sharing the page URL shares the initial view, not the current configuration.

When withHistory is enabled, every state change is also written to the browser URL as query parameters using history.pushState. Reading the current state works in reverse — instead of checking the in-memory object, the component parses window.location.search. This means:

  • Refreshing the page restores the exact configurator state
  • Copying and sharing the URL shares the exact configuration
warning

Browser back/forward buttons will change the URL (because the embed uses history.pushState), but the embed component does not listen for popstate events. This means pressing the back button updates the address bar but does not update the configurator view. The user would need to refresh the page for the configurator to read the new URL and render the corresponding state. Keep this in mind when building navigation flows — if you need true back/forward support, you would need to implement your own popstate listener that triggers a re-render or page reload.

The Update Flow​

Here is what happens internally when a user interacts with the configurator:

  1. The inner application (configurator, product list, modular scene) dispatches a navigation event through the onEventDispatch callback. This event carries an action type and relevant data (variant code, short code, tab hash, etc.).

  2. The watchEvents method in the embed component receives this event and routes it based on the action type — configurator navigation, tab selection, AR generation, go-back, favourites toggle, and so on.

  3. For each action, the component calls updateURL(data) with the new query parameters. If withHistory is enabled, this calls history.pushState to update the address bar. If disabled, it only updates the in-memory state object.

  4. The component then mounts the appropriate view (configurator, product list, AR page, etc.) with the new parameters.

  5. On subsequent reads — such as page load or when determining current state — getLastData() either parses window.location.search (with history) or returns the in-memory object (without history).

URL Query Parameters​

When URL navigation is active, the following parameters may appear in the browser's address bar. Not all parameters are present at all times — only those relevant to the current state are included. Empty or undefined values are omitted.

ParameterTypeDescription
variantCodestringFull variant code of the currently displayed product (e.g., CHAIR=Color-a1&Size-a2). Present when a configurator is open.
shortCodestringScene short code. Present for modular products to identify the scene being configured.
isModularbooleanSet to true when the active configurator is a modular scene.
tabstringID of the currently selected product tab (options, gallery, related, etc.).
categorystringActive product category path in a product list view.
isFavouritesbooleanSet to 1 when the favourites view is active within a product list.
favouritesstringActive favourite collection path.
arShortCodestringAR short code when viewing the AR landing page.
incompatiblebooleanSet to true when the device is incompatible with AR but the AR page is still shown.
allowScalingbooleanWhether AR model scaling is allowed.
finishScreenbooleanModular products only. When set to true, the configurator opens directly to the elements list (finish/summary view) instead of the 3D scene. This is primarily useful for e-commerce flows — for example, when a customer returns from the cart to review their configuration, a manufacturer may want to show the list of selected elements rather than reloading the full scene.
cartRefstringCart reference code when previewing a basket item in the configurator.

Example URLs​

Standard product configurator:

https://example.com/products?variantCode=CHAIR%3DColor-a1%26Size-a2&tab=options

Modular product:

https://example.com/products?variantCode=DESK%3DFrame-a1&shortCode=SC123&isModular=true

Modular product — elements list (e-commerce cart return):

https://example.com/products?variantCode=DESK%3DFrame-a1&shortCode=SC123&isModular=true&finishScreen=true

Product list with category filter:

https://example.com/products?category=office-furniture

AR view:

https://example.com/products?variantCode=CHAIR&arShortCode=AR789&allowScaling=true

Favourites view:

https://example.com/products?isFavourites=1&favourites=my-collection
tip

The variantCode in the URL follows the standard configuration code structure: {productPrefix}={blockOption pairs}. For details on how this code is composed, see the Configuration Code Structure documentation.

Behavior by Embed Type​

URL navigation works differently depending on what type of embed short code you're using. The embed type is determined by how the short code was created in the Mimeeq admin panel.

Single Product Embed (CONFIGURATOR)​

This is the most common embed type — a single product configurator.

On initial load: The component reads URL parameters via getLastData(). If variantCode is present in the URL, it loads that specific configuration. If no variantCode is found but renderAtMount is enabled (the default), it loads the product's default configuration using the product prefix.

During interaction: Each option change within the configurator triggers a mimeeq-app-url-change event internally, which propagates through the navigation system. The variantCode parameter in the URL updates to reflect the new configuration. Tab changes update the tab parameter.

Modular products: When the single product embed contains a modular product, the isModular and shortCode parameters are added. The shortCode identifies the scene configuration. If the variant code contains a / separator (format variantCode/sceneShortCode), the component splits it and handles both parts. The finishScreen parameter is exclusive to modular products — when set to true, the configurator opens directly to the elements list instead of the 3D scene. This is useful in e-commerce flows where a customer navigates back from the cart and the integrator wants to show a summary of selected elements rather than re-rendering the full modular scene.

AR navigation: When a user clicks "View in your room", the arShortCode, allowScaling, and incompatible parameters are added. Returning from AR removes these and restores the previous configurator parameters.

Product List / Product Group Embed (PRODUCTGROUPLIST)​

This embed type shows a list of products that users can browse and then open individual configurators from.

On initial load: The component checks for variantCode in the URL. If present, it skips the list view and opens the configurator directly — this is what makes shared configuration links work. If no variant code is present, it shows the product list, optionally filtered by category or showing favourites if isFavourites is set.

Product selection: When a user clicks a product in the list, the component mounts the configurator and updates the URL with the product's variantCode (and shortCode/isModular if applicable).

Going back: When the user clicks back (either via browser back button or the in-app back button), the configurator parameters (variantCode, shortCode, isModular) are removed from the URL. If showMenuControls is enabled, the category and favourites parameters are preserved so the list returns to its previous filter state. If showMenuControls is disabled, the URL is cleared entirely.

Favourites toggle: Opening favourites sets isFavourites=1 in the URL. Closing favourites either removes all parameters (if showMenuControls is off) or sets isFavourites=0 (if showMenuControls is on).

Favourites-Only Embed (FAVOURITESLIST)​

Behaves like a product list embed but is restricted to showing only the user's saved favourite configurations. The URL parameter favourites tracks the active collection. Navigation into and out of individual product configurators follows the same patterns as the product list embed.

Basket Embed (BASKET)​

Basket embeds always have URL navigation enabled regardless of the withHistory setting. The cartRef parameter tracks which basket item is being previewed in the configurator. This ensures that basket preview links are always shareable.

Automatic Configurator Display with URL Parameters​

One of the most practical benefits of URL navigation is that shared configuration links work automatically. When a user visits a page containing mmq-embed with with-history enabled and the URL contains a variantCode parameter, the configurator automatically opens and displays that configuration. No additional JavaScript is needed.

This is useful for:

  • Sharing product configurations via email or social media
  • Direct links from marketing campaigns
  • QR codes leading to specific configurations
  • Restoring in-progress configurations after page refresh
<!-- This is all you need — the URL parameters do the rest -->
<mmq-embed short-code="YOUR_SHORT_CODE" template="your_template" with-history></mmq-embed>

For exceptional cases where you need manual control over this behavior:

// Check if URL contains configuration parameters and manually trigger display
window.onload = () => {
  if (window.location.href.indexOf('variantCode') > -1) {
    document.addEventListener('mimeeq-app-loaded', () => {
      const configurator = document.querySelector('mmq-embed');
      if (configurator) {
        configurator.show();
      }
    });
  }
};
warning

If you're using with-history but the configurator doesn't auto-show when the URL contains parameters, check that renderAtMount is enabled in your embed template settings (it is true by default). The configurator only renders on page load if either renderAtMount is true or a variantCode is present in the URL.

URL Navigation Without withHistory​

When withHistory is disabled, the embed component still tracks navigation state internally using the same QueryParams structure — it just doesn't write it to the URL. All internal navigation (product selection, tab switching, going back) works identically. The only difference is:

  • The browser URL never changes
  • Page refresh resets the configurator to its initial state
  • Configuration links cannot be shared via URL

This is fine for simple integrations where sharing is handled through other means (e.g., short codes passed through your own system, or mimeeq-add-to-cart event payloads stored in your database).

Important Considerations​

URL encoding: Query parameter values are URL-encoded. The = and & characters within variant codes get encoded (e.g., CHAIR=Color-a1&Size-a2 becomes CHAIR%3DColor-a1%26Size-a2). The parseSearch and createSearch utilities handle this transparently.

Hash fragment preservation: When the URL is updated, the existing hash fragment (#section) is preserved. The embed component does not use the hash for its own state.

Single embed per page: Because URL navigation writes to window.location, only one mmq-embed component with withHistory enabled should exist on a page. Multiple history-enabled embeds would overwrite each other's URL parameters. If you need multiple products on one page, use a single embed and switch its short-code attribute dynamically.

Embed instance filtering: Navigation events carry an embedInstanceId. The watchEvents handler ignores events from other embed instances, preventing cross-talk if multiple embeds are present (though only one should use withHistory).

Custom query parameters: The embed component preserves query parameters it doesn't recognize. If your page URL already contains custom parameters (e.g., ?utm_source=email), they will be retained when the embed updates the URL with its own parameters.