> 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). # Theme Extension Learn how to integrate Mimeeq with your Shopify store using theme app extensions. ## Content 1. [Setup Your Theme](#setup-your-theme) 2. [Add and Configure Mimeeq Configurator Block](#add-and-configure-mimeeq-configurator-block) 3. [Add and Configure Mimeeq Button Block](#add-and-configure-mimeeq-button) 4. [Configure Error Handling](#configure-error-handling) 5. [Cart Processing Tooltips](#cart-processing-tooltips) 6. [Test and Finalize](#test-and-finalize) 7. [Additional Mimeeq Blocks](#additional-mimeeq-blocks) In this article, you will learn how to add your configurators to your storefront using our theme app extension. Our app extension works with themes built with Online Store 2.0, which uses Shopify's drag and drop theme editor. {% hint style="warning" %} You should first read this guide: [Shopify App - 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 %} ## Setup Your Theme **Step 1: Customize Theme** Click on "Customize Theme" in your Shopify admin to access the theme editor. ![Customize Theme](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) **Step 2: Navigate to Product Templates** Navigate to the Product Templates section in the theme editor. ![Product Templates](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) **Step 3: Select Your Template** This can be **any template** - it does not have to be the Mimeeq product template shown in the screenshot (this was created for our demo purposes). However, using 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. ![Select 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) ## Add and Configure Mimeeq Configurator Block Mimeeq offers two blocks for adding configurators: 1. **Dynamic Configurator Block:** Use on product pages where each Shopify product already has an assigned shortcode. Automatically connects to the viewed product, can load with or without a button based on your Mimeeq template settings. ![Dynamic Configurator Block](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. ![Enter Mimeeq Embed Template ID](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) 2. **Standalone Embed Block:** Use on any other page (homepage, landing pages) or when you don't need Shopify product management. Requires both a Shortcode and Template ID. Ideal for stores with a single customizable product. ### Skeleton loader The skeleton loader displays a placeholder layout while the configurator is loading, giving customers a polished experience instead of a blank space or layout jump. It automatically removes itself once the configurator is ready. Loader is built into the **Dynamic and Standalone Embed Configurator** block. To enable it, select the **Dynamic and Standalone Embed Configurator** block in your theme editor and toggle on **Enable skeleton loader** under **Skeleton Loader Settings**. {% 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 is set to launch via a button that opens a modal, the skeleton loader will have no effect. {% endhint %} **Layout settings** These settings control the size and proportions of the skeleton loader to match your configurator layout. | Name | Description | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Adjust to container | Makes the skeleton loader fill the available container width. Enable this if your configurator is placed inside a constrained layout. When enabled, the **Maximum Width** setting is hidden, as the loader will take up all available space within the container. | | Padding Top | Space above the skeleton loader (px). Default: `0`. | | Padding Bottom | Space below the skeleton loader (px). Default: `0`. | | Dimensions Unit | Unit used for the loader height on desktop — either **Pixels (px)** or **Viewport (vh)**. | | Loader Height | Total height of the skeleton loader. Default: `900 px`. | | Mobile Dimensions Unit | Unit used for the loader height on mobile — either **Pixels (px)** or **Viewport (vh)**. | | Mobile Loader Height | Height of the skeleton loader on mobile devices. Default: `100 vh`. | | Maximum Width | Only visible when Adjust to container is disabled. Prevents the loader from expanding beyond this width. | | Side Panel Width | Width of the configuration side panel placeholder. Set this to match the side panel width in your embed template. Default: `380 px`. | | Element Border Radius | Rounds the corners of internal panels and placeholders. Default: `4 px`. | **Colour settings** Customize 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. | Name | Description | | ---------------------------- | --------------------------------------------------------------------------- | | Base Background Color | Background colour outside the main 3D canvas and panel. Default: `#F4F4F4`. | | Placeholder Background Color | Base colour for text and layout skeleton "bones". Default: `#E4E5E7`. | | Shimmer Animation Effect | Colour of the loading sweep animation overlay. Default: `#FFFFFB3`. | {% hint style="info" %} Note: 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](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 Mimeeq Button If your embed template is set to load with a button, you can add and customize a Mimeeq button. There are two button types available: 1. **Mimeeq Simple Button** (the original button with basic customization options). 2. **Mimeeq Advanced Button** (offers significantly more customization options). Drag the button block to your desired location on the page. {% hint style="warning" %} The Advanced Button was launched on August 21, 2025. If you created a button block before this date, you are probably still using the Simple Button. {% endhint %} ![Mimeeq Button Block](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) ### Customize Button Appearance You can customize and use both Simple and Advanced buttons in your store. Here's what settings are available in each button type:
SettingSimple ButtonAdvanced 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 customization beyond these settings, you can use CSS to style the Mimeeq button by targeting \. {% endhint %} ![Button Settings](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 configurator, you can customize various error handling elements. First add the **App Error Modal** block to your theme and then you can customize available content. {% hint style="info" %} Learn More: You can find detailed information about [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
Modal TypeWhen It Appears
Cart Error Lodal Displays when a product cannot be added to the cart.
Embed Error Modal Displays when the configurator fails to load on the page.
Price Error Modal Displays when product pricing cannot be calculated or shows invalid values
Availability Error Modal Displays when one or more items in the design are currently unavailable.
![Error Modal Settings](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 customize and change. Each modal has different illustration, but the layout stays the same. Here is an example of how this modal can look like: ![Modal Example](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 recovery information so you can contact them and not lose the sale. You will receive an email with all submitted information, and it will also be stored in the [Error Recovery Center.](/commerce-and-integrations/shopify/error-recovery.md) {% hint style="warning" %} Note: Only the email field is required to submit the form. {% endhint %}
FieldDescriptionType
Name Field Placeholder Placeholder text for Name input Text
Email Field Placeholder Placeholder text for email input Text
Optional Message Field Placeholder Placeholder text for message textarea Text
Submit Button Label Text displayed on submit button Text
Optional Disclaimer Checkbox text (e.g., Privacy Policy acceptance) Text + Checkbox
![Recovery Form Settings](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 Displays after customer successfully submits the recovery form. This modal will automatically close after 3 seconds.
SettingDescription
Modal Title Title shown when recovery data is successfully submitted
Modal Content Message content displayed in success modal
![Success Modal Settings](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 will appear after a configurable delay if the cart action is still processing. **Setting 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 %}
SettingDescription
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 Customization Customize the appearance of the tooltip notification to match your store's branding. | **Setting** | **Description** | | ------------------ | ----------------------------------------------- | | Background color | Background color of the notification | | Text color | Color of the message text | | Border color | Color of the notification border | | Progress bar color | Color of the loading progress indicator | | Icon | Choose from: None, Cart, Clock, Magic, Light | | Icon color | Color of the selected icon and dismissal icon X | #### Content Settings Customize the message content for each notification stage. | **Setting** | **Description** | | -------------- | ------------------------------------------------------------------------------------------------------------ | | First message | Initial message shown to customers (e.g., "Hmm this masterpiece is taking longer than normal to prepare") | | Second message | Message shown during extended wait (e.g., "Stay with us, we are working our magic behind the scenes") | | Third message | Final message before error (e.g., "Our servers must be overloaded today, this is taking longer than normal") | ![Delay Toast Messages Settings](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 Finalize 1. Ensure the preview product has Mimeeq metafields completed properly 2. Click the View link to test that the configurator loads and functions correctly 3. Save your changes ![Preview Changes](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 allows you to customize interface text with quick access to the 4 most popular fields: {% hint style="warning" %} Mimeeq Embed Translations block should be added to the same page as your configurator. {% endhint %} * **Add to Cart Button**: Customize the purchase button text * **View in Room (AR Button)**: Customize AR functionality text * **Required Warning Messages**: Set validation messages * **Custom Delivery Information**: Add delivery details Additionally, there's a box where you can paste your translation keys from Mimeeq to customize the entire configurator UI. ![Additional Mimeeq Blocks](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 Help Articles * [Error Recovery Center Guide](/commerce-and-integrations/shopify/error-recovery.md) * [Shopify App - Admin Settings](/commerce-and-integrations/shopify/admin-settings.md) * [Shopify Latest Version Updates](/commerce-and-integrations/shopify/changelog.md) --- # 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 current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.mimeeq.com/commerce-and-integrations/shopify/theme-extension.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.