> For the complete documentation index, see [llms.txt](https://help.mimeeq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.mimeeq.com/configurator/advanced-customisation/javascript-api.md).

# 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:

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

For more code examples and for selecting multiple options, check out our [developer documentation](https://docs.mimeeq.com/embeds-utils#mark-option-by-block-name-and-option-code).

{% hint style="warning" %}
The block name and code are case sensitive.
{% endhint %}

![Option block name field in the Mimeeq app](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2Fca8RrFgt705DmpjsBMLf%2Fblock-name_aqnaaq.png?alt=media)

![Option code field in the Mimeeq app](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FRRczkyl1ksX5268Vs4Jn%2Fcode_1pph8x8.png?alt=media)

***

## 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

{% hint style="warning" %}
Do not add this block to the Mimeeq option panel. It will still be active and controllable, but it will be hidden from view.
{% endhint %}

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](/configurator/rules/overview.md).
   * 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](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FgpSWTMk8EpO7rwO4PBdN%2Fhidden-option-settings_13pw5yi.png?alt=media)

### 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.

```html
<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.

{% embed url="<https://codepen.io/mimeeq/embed/dyLpwdX?default-tab=>" %}
CODEPEN DEMO
{% endembed %}

Watch the video explanation:

{% embed url="<https://www.loom.com/embed/8d86fb92adf34f9b858461ac97f6cff2?sid=4057e07e-3fca-4fb5-8c62-24963da64191>" %}
Controlling Mimeeq's Configurator with our JS API
{% endembed %}

{% hint style="info" %}
If you have a use case and need help, reach out to us using the chat widget in the bottom-right corner.
{% endhint %}

***

## Related articles

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Rules Overview</strong></td><td>Understand the structure of rules and how triggers and actions work together.</td><td><a href="/configurator/rules/overview.md">Rules Overview</a></td></tr><tr><td><strong>Hiding Options</strong></td><td>Control which options are visible to users and which are used only for pricing or rules.</td><td><a href="/configurator/options-and-widgets/hiding-options.md">Hiding Options</a></td></tr><tr><td><strong>Button Widget</strong></td><td>Add buttons to reset options, guide users through flows, or fire JavaScript events.</td><td><a href="/configurator/options-and-widgets/button-widget.md">Button Widget</a></td></tr><tr><td><strong>Custom UI Requirements</strong></td><td>Technical requirements and guidelines for building a custom configurator interface.</td><td><a href="/configurator/advanced-customisation/custom-ui-requirements.md">Custom UI Requirements</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.mimeeq.com/configurator/advanced-customisation/javascript-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.