> 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/commerce-and-integrations/shopify/theme-extension.md).

# Shopify Theme Extension

Add Mimeeq configurators, buttons and error handling to your Shopify storefront. Learn to set up each Mimeeq app block in the Shopify theme editor.

Add your configurators to your storefront using our theme app extension. The extension works with themes built with Online Store 2.0, which uses Shopify's drag-and-drop theme editor.

{% hint style="info" %}
Before you start, read [Shopify Admin Settings](/commerce-and-integrations/shopify/admin-settings.md) to connect your configurators with your existing Shopify products and add your Mimeeq API key.
{% endhint %}

***

## Set up your theme

{% stepper %}
{% step %}

### Customise theme

Click **Customize Theme** in your Shopify admin to open the theme editor.

![Shopify admin with the Customize Theme button](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FGBg3c2Ok15iePTW1mUN3%2Fshopify-help-theme-11_178zriv.png?alt=media)
{% endstep %}

{% step %}

### Navigate to product templates

Navigate to the **Product Templates** section in the theme editor.

![Theme editor page selector showing the Product Templates section](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FCGzOdYkEr8lRoh6GGbyB%2Fshopify-help-theme-211_17piby6.png?alt=media)
{% endstep %}

{% step %}

### Select your template

This can be **any template**. It does not have to be the Mimeeq product template shown in the screenshot, which was created for demo purposes. A clear name like "Mimeeq Product" helps indicate which products are connected with Mimeeq.

To create a new template, click **New Template** following standard Shopify logic.

![List of product templates in the theme editor, including a Mimeeq Product template](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FMJPIJjmNJOldPxVnrILy%2Fshopify-help-theme-311_t07nom.png?alt=media)
{% endstep %}
{% endstepper %}

***

## Add and configure the Mimeeq configurator block

Mimeeq offers two blocks for adding configurators. Choose the one that fits the page.

{% tabs %}
{% tab title="Dynamic Configurator Block" %}
Use on product pages where each Shopify product already has an assigned shortcode. It automatically connects to the viewed product and can load with or without a button, based on your Mimeeq template settings.

![Adding the Dynamic Configurator block to a product template](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FcQiXJ2rmwPqYmnZhRFu9%2Fshopify-help-theme-511_ikaowh.png?alt=media)

After adding the Dynamic Configurator, enter the **Mimeeq Embed Template ID**.

![Mimeeq Embed Template ID field in the Dynamic Configurator block settings](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FVAHQlXhjJbFNOOZRZQRt%2Fshopify-help-theme-6-new_z5hers.png?alt=media)
{% endtab %}

{% tab title="Standalone Embed Block" %}
Use on any other page (homepage, landing pages) or when you don't need Shopify product management. It requires both a **Shortcode** and a **Template ID**. Ideal for stores with a single customisable product.
{% endtab %}
{% endtabs %}

### Skeleton loader

The skeleton loader displays a placeholder layout while the configurator is loading. Customers see a polished experience instead of a blank space or layout jump. It removes itself automatically once the configurator is ready.

The loader is built into the **Dynamic and Standalone Embed Configurator** block.

{% hint style="warning" %}
**Important:** The skeleton loader only works when the configurator is embedded inline on a page. It is not supported when the configurator opens as a modal. If your embed template launches via a button that opens a modal, the skeleton loader will have no effect.
{% endhint %}

To enable it:

1. Select the **Dynamic and Standalone Embed Configurator** block in your theme editor.
2. Under **Skeleton Loader Settings**, toggle on **Enable skeleton loader**.

#### Layout settings

These settings control the size and proportions of the skeleton loader to match your configurator layout.

<table><thead><tr><th width="253.046875">Name</th><th>Description</th></tr></thead><tbody><tr><td><strong>Adjust to container</strong></td><td>Makes the skeleton loader fill the available container width. Enable this if your configurator is placed inside a constrained layout. When enabled, the <strong>Maximum Width</strong> setting is hidden, as the loader takes up all available space within the container.</td></tr><tr><td><strong>Padding Top</strong></td><td>Space above the skeleton loader (px). Default: <code>0</code>.</td></tr><tr><td><strong>Padding Bottom</strong></td><td>Space below the skeleton loader (px). Default: <code>0</code>.</td></tr><tr><td><strong>Dimensions Unit</strong></td><td>Unit used for the loader height on desktop: either <strong>Pixels (px)</strong> or <strong>Viewport (vh)</strong>.</td></tr><tr><td><strong>Loader Height</strong></td><td>Total height of the skeleton loader. Default: <code>900 px</code>.</td></tr><tr><td><strong>Mobile Dimensions Unit</strong></td><td>Unit used for the loader height on mobile: either <strong>Pixels (px)</strong> or <strong>Viewport (vh)</strong>.</td></tr><tr><td><strong>Mobile Loader Height</strong></td><td>Height of the skeleton loader on mobile devices. Default: <code>100 vh</code>.</td></tr><tr><td><strong>Maximum Width</strong></td><td>Only visible when <strong>Adjust to container</strong> is disabled. Prevents the loader from expanding beyond this width.</td></tr><tr><td><strong>Side Panel Width</strong></td><td>Width of the configuration side panel placeholder. Set this to match the side panel width in your embed template. Default: <code>380 px</code>.</td></tr><tr><td><strong>Element Border Radius</strong></td><td>Rounds the corners of internal panels and placeholders. Default: <code>4 px</code>.</td></tr></tbody></table>

#### Colour settings

Customise the skeleton loader's colours to match your store's theme. All colour fields support a colour picker as well as direct hex/RGBA input.

<table><thead><tr><th width="247.84375">Name</th><th>Description</th></tr></thead><tbody><tr><td><strong>Base Background Color</strong></td><td>Background colour outside the main 3D canvas and panel. Default: <code>#F4F4F4</code>.</td></tr><tr><td><strong>Placeholder Background Color</strong></td><td>Base colour for text and layout skeleton "bones". Default: <code>#E4E5E7</code>.</td></tr><tr><td><strong>Shimmer Animation Effect</strong></td><td>Colour of the loading sweep animation overlay. Default: <code>#FFFFFB3</code>.</td></tr></tbody></table>

{% hint style="success" %}
**Tip:** Match the **Side Panel Width** and colours to your embed template settings. A well-matched skeleton loader avoids a visible layout shift when the configurator finishes loading.
{% endhint %}

![Skeleton Loader Settings panel in the theme editor](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2Fy4sUAXGRH68CIKhocR4i%2Fshopify-help-theme-17-new_iydodq.png?alt=media)

***

## Add and configure the Mimeeq button

If your embed template is set to load with a button, you can add and customise a Mimeeq button. There are two button types:

* **Mimeeq Simple Button**: the original button with basic customisation options
* **Mimeeq Advanced Button**: offers significantly more customisation options

Drag the button block to your desired location on the page.

{% hint style="warning" %}
The Advanced Button was launched on 21 August 2025. If you created a button block before this date, you are probably still using the Simple Button.
{% endhint %}

![Mimeeq button blocks in the theme editor block list](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FOZLlvvmf6JNoxEjaxCzu%2Fshopify-help-theme-41_1nr6nj3.png?alt=media)

### Customise button appearance

You can customise and use both Simple and Advanced buttons in your store. These settings are available in each button type:

| Setting                      | Simple Button   | Advanced Button                                                        |
| ---------------------------- | --------------- | ---------------------------------------------------------------------- |
| **Label**                    | ✅               | ✅                                                                      |
| **Background Colour**        | ✅               | ✅                                                                      |
| **Text Colour**              | ✅               | ✅                                                                      |
| **Shape**                    | ❌               | ✅ (Rounded, Pill, Rectangle, Custom)                                   |
| **Border Colour**            | ❌               | ✅ (Gradient or Custom)                                                 |
| **Icon**                     | ❌               | ✅ (Palette, Brush, Magic Wand, None)                                   |
| **Icon Colour**              | ❌               | ✅ (Gradient or Custom)                                                 |
| **Hover Background Color**   | ✅ (Only Custom) | ✅ (Gradient or Custom)                                                 |
| **Text Hover Color**         | ✅               | ✅                                                                      |
| **Icon Hover Color**         | ❌               | ✅ (Gradient or Custom)                                                 |
| **Idle Animation Type**      | ❌               | ✅ (Shimmer, Border Pulse, Glow Pulse, Corner Sweep, Wave Border, None) |
| **Idle Animation Speed**     | ❌               | ✅ (2 seconds, 3.5 seconds, 5 seconds, Custom)                          |
| **Idle Animation Intervals** | ❌               | ✅ (Every 2 seconds, Every 3.5 seconds, Every 5 seconds, Custom)        |
| **Repeat Idle Animation**    | ❌               | ✅ (1–3 times, Custom, Infinite)                                        |
| **Top/Bottom Padding**       | ❌               | ✅                                                                      |
| **Left/Right Padding**       | ❌               | ✅                                                                      |
| **Vertical Margin**          | ✅               | ✅                                                                      |

{% hint style="info" %}
For additional customisation beyond these settings, you can use CSS to style the Mimeeq button by targeting `button.mmq-button`.
{% endhint %}

![Button block settings in the theme editor](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FIaJPaaKVtSYXCdSEVLYU%2Fshopify-help-theme-71_1xo5q0r.png?alt=media)

***

## Configure error handling

If customers experience issues with the configurator, you can customise various error handling elements. First add the **App Error Modal** block to your theme, then customise the available content.

{% hint style="info" %}
**Learn more:** see [setting up notifications](/commerce-and-integrations/shopify/error-notifications.md) and how the [Error Recovery Center](/commerce-and-integrations/shopify/error-recovery.md) works in our dedicated guides.
{% endhint %}

### Error modal types

<table><thead><tr><th width="257.48828125">Modal type</th><th>When it appears</th></tr></thead><tbody><tr><td><strong>Cart Error Modal</strong></td><td>Displays when a product cannot be added to the cart.</td></tr><tr><td><strong>Embed Error Modal</strong></td><td>Displays when the configurator fails to load on the page.</td></tr><tr><td><strong>Price Error Modal</strong></td><td>Displays when product pricing cannot be calculated or shows invalid values.</td></tr><tr><td><strong>Availability Error Modal</strong></td><td>Displays when one or more items in the design are currently unavailable.</td></tr></tbody></table>

![App Error Modal block settings in the theme editor](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FK2M64SQ5NPl0nzFU1iM3%2Fshopify-help-theme-81_ur8rar.png?alt=media)

Each modal has title, description and content fields that you can customise. Each modal has a different illustration, but the layout stays the same. Here is an example of how a modal can look:

![Example error modal on the storefront with illustration, message and recovery form](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2F0rrGv3AH0HoPhhc4kHoO%2F1_8ypu4z.png?alt=media)

### Recovery form settings

When customers experience errors, they can submit their contact information so you can reach them and not lose the sale. You receive an email with all submitted information, and it is also stored in the [Error Recovery Center](/commerce-and-integrations/shopify/error-recovery.md).

{% hint style="info" %}
**Note:** Only the email field is required to submit the form.
{% endhint %}

| Field                                  | Description                                    | Type            |
| -------------------------------------- | ---------------------------------------------- | --------------- |
| **Name Field Placeholder**             | Placeholder text for the name input            | Text            |
| **Email Field Placeholder**            | Placeholder text for the email input           | Text            |
| **Optional Message Field Placeholder** | Placeholder text for the message text area     | Text            |
| **Submit Button Label**                | Text displayed on the submit button            | Text            |
| **Optional Disclaimer**                | Checkbox text (e.g. Privacy Policy acceptance) | Text + Checkbox |

![Recovery form settings in the theme editor](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FKLdYa6N14U0dYaneNQim%2Fshopify-help-theme-141_1fbfsoz.png?alt=media)

### Success modal settings

The success modal displays after a customer submits the recovery form. It closes automatically after 3 seconds.

| Setting           | Description                                              |
| ----------------- | -------------------------------------------------------- |
| **Modal Title**   | Title shown when recovery data is successfully submitted |
| **Modal Content** | Message content displayed in the success modal           |

![Success modal settings in the theme editor](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FxyPScFEchggksmWNQ39q%2Fshopify-help-theme-101_10cob9h.png?alt=media)

***

## Cart processing tooltips

The Cart Processing Tooltip displays progressive notifications to keep customers informed when adding products to the cart takes longer than expected. An error modal appears after a configurable delay if the cart action is still processing.

**To set up processing tooltips:**

1. Add the **Cart Processing Tooltip** block to your theme.
2. Configure the timing, visual appearance and message content.

### Timing settings

Configure when each message should appear. Messages show one at a time in sequence.

{% hint style="warning" %}
**Important:** Make sure each timing value is greater than the previous one to avoid conflicts.
{% endhint %}

| Setting                            | Description                                                                      |
| ---------------------------------- | -------------------------------------------------------------------------------- |
| **First message delay (seconds)**  | Time in seconds before the first notification displays                           |
| **Second message delay (seconds)** | Time in seconds before the second notification displays                          |
| **Third message delay (seconds)**  | Time in seconds before the third notification displays                           |
| **Error modal delay (seconds)**    | Time in seconds before the error modal appears if processing is still incomplete |

### Visual customisation

Customise the appearance of the tooltip notification to match your store's branding.

<table><thead><tr><th width="281.6953125">Setting</th><th>Description</th></tr></thead><tbody><tr><td><strong>Background color</strong></td><td>Background colour of the notification</td></tr><tr><td><strong>Text color</strong></td><td>Colour of the message text</td></tr><tr><td><strong>Border color</strong></td><td>Colour of the notification border</td></tr><tr><td><strong>Progress bar color</strong></td><td>Colour of the loading progress indicator</td></tr><tr><td><strong>Icon</strong></td><td>Choose from: None, Cart, Clock, Magic, Light</td></tr><tr><td><strong>Icon color</strong></td><td>Colour of the selected icon and the dismissal icon (X)</td></tr></tbody></table>

### Content settings

Customise the message content for each notification stage.

<table><thead><tr><th width="234.07421875">Setting</th><th>Description</th></tr></thead><tbody><tr><td><strong>First message</strong></td><td>Initial message shown to customers (e.g. "Hmm this masterpiece is taking longer than normal to prepare")</td></tr><tr><td><strong>Second message</strong></td><td>Message shown during an extended wait (e.g. "Stay with us, we are working our magic behind the scenes")</td></tr><tr><td><strong>Third message</strong></td><td>Final message before the error (e.g. "Our servers must be overloaded today, this is taking longer than normal")</td></tr></tbody></table>

![Cart Processing Tooltip block settings with delay and message fields](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FjVbx60fQT0wdNOroOnLH%2Fshopify-help-theme-131-new_ywgonu.png?alt=media)

***

## Test and finalise

1. Ensure the preview product has its Mimeeq metafields completed properly.
2. Click the **View** link to test that the configurator loads and functions correctly.
3. Save your changes.

![Theme editor preview with the View link and Save button](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FM1FqXyk1H2bQa2fhrEIK%2Fshopify-help-theme-111_1m3j0q9.png?alt=media)

***

## Additional Mimeeq blocks

### Mimeeq Embed Translations

This app block lets you customise interface text, with quick access to the 4 most popular fields:

* **Add to Cart Button**: customise the purchase button text
* **View in Room (AR Button)**: customise AR functionality text
* **Required Warning Messages**: set validation messages
* **Custom Delivery Information**: add delivery details

There's also a box where you can paste your translation keys from Mimeeq to customise the entire configurator UI.

{% hint style="warning" %}
Add the **Mimeeq Embed Translations** block to the same page as your configurator.
{% endhint %}

![Mimeeq Embed Translations block settings in the theme editor](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FUDdGe6FZkU4ahFuI5U9D%2Fshopify-help-theme-121_13zmnzb.png?alt=media)

***

## 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>Shopify Admin Settings</strong></td><td>Connect your API key, products and cart settings.</td><td><a href="/commerce-and-integrations/shopify/admin-settings.md">Shopify Admin Settings</a></td></tr><tr><td><strong>Shopify Error Recovery Center</strong></td><td>Track errors and follow up with affected customers.</td><td><a href="/commerce-and-integrations/shopify/error-recovery.md">Shopify Error Recovery Center</a></td></tr><tr><td><strong>Shopify Error Notifications</strong></td><td>Get email alerts when customers hit configurator or cart errors.</td><td><a href="/commerce-and-integrations/shopify/error-notifications.md">Shopify Error Notifications</a></td></tr><tr><td><strong>Shopify Multi-Currency &#x26; Markets</strong></td><td>Show regional prices in multiple currencies.</td><td><a href="/commerce-and-integrations/shopify/multi-currency-and-markets.md">Shopify Multi-Currency &amp; Markets</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 dynamically 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/commerce-and-integrations/shopify/theme-extension.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 `build a script that syncs our docs to a CMS` 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.