JavaScript API

Control the Mimeeq configurator from your own code and add custom logic. Learn how to run a headless canvas and drive rules with external values like quantity.

Mimeeq supports the ability for clients to extend our configurator logic using custom JavaScript. Below, you'll find practical examples along with code snippets to guide you through the process.

---

Example 1: headless canvas

Mimeeq's configurator can be used in a fully or partially headless capacity. This allows you to hide our options panel and integrate your own, while controlling our canvas with simple JavaScript commands.

Practical example

Imagine you have a sofa that comes in 10 fabrics and 5 wood leg finishes. In Mimeeq, the option block code for fabrics is called SeatFinishes, and the code for the fabric is AM003. In this scenario, you would use the following JavaScript command to mark the option block and code:

await mimeeqApp.actions.markOptionByBlockNameAndOptionCode('SeatFinishes', 'AM003');

For more code examples and for selecting multiple options, check out our developer documentation.

The block name and code are case sensitive.

Option block name field in the Mimeeq app

Option code field in the Mimeeq app

---

Example 2: extend rules logic using external values such as quantity

In this example, if the quantity is 10 or more, the customer can pick a custom paint colour for the legs of the armchair. If the quantity is less than 10, they can choose from only one of five predefined options.

Set up the hidden option block

Do not add this block to the Mimeeq option panel. It will still be active and controllable, but it will be hidden from view.

1. Create an option block called "Hidden JS Qty Control" in the Mimeeq app. The name can be anything you like.

2. Add two options to choose from, with any names and codes you prefer. In this example, I use "Show" and "Hide".

3. Toggle the Hide on specification option to ensure this block will be hidden from cart specifications, including Mimeeq's Basket.

4. Name the block something unique and easy to recognise, such as "qty10".

5. Use these two options as triggers to set up your rules. For more information on rules, refer to Rules Overview.

   • When Show is selected, the colour picker will be displayed, a material override action will be implemented, and a message widget will inform the customer about this new option.

   • When Hide is selected, a different message will be displayed, the colour picker will not be shown, and the standard option will be maintained.

Hidden option block settings with Hide on specification enabled

Add the JavaScript code

The code below listens for quantity change events. If the quantity is greater than or equal to 10, it selects the "show" option using the command from Example 1. If the quantity is less than 10, it selects the "hide" option.

<script>
    let subscription;
    document.addEventListener('mimeeq-3d-product-initialized', () => {
      console.log('Product initialized');
      if(!subscription) {
          subscription = mimeeqApp.observers.pricing.quantity.subscribe(({newValue, oldValue}) => {
              mimeeqApp.actions.markOptionByBlockNameAndOptionCode('qty10', newValue < 10 ? 'hide' : 'show');
          })  
      }
    })

    document.addEventListener('mimeeq-leave-product', () => {
      if(subscription) {
        subscription.unsubscribe();
        subscription = undefined;
      }
    })
</script>

Try it

Here is a working example to try. Change the quantity to 10 and then back to 9.

CODEPEN DEMO

Watch the video explanation:

Controlling Mimeeq's Configurator with our JS API

If you have a use case and need help, reach out to us using the chat widget in the bottom-right corner.

---

Related articles

Rules Overview

Understand the structure of rules and how triggers and actions work together.

Hiding Options

Control which options are visible to users and which are used only for pricing or rules.

Button Widget

Add buttons to reset options, guide users through flows, or fire JavaScript events.

Custom UI Requirements

Technical requirements and guidelines for building a custom configurator interface.