Shopify Instant variant images: setup guide for Instant page builder
Instant is a simple and intuitive page builder app that helps you create beautifully crafted Shopify product pages. Problem: Instant contains custom layouts which often confuse variant image apps expecting a default product format. Result: empty galleries, incorrect product images, no product swatches.
Rubik Variant Images comes with built-in Instant detection and has a number of features that enable it to detect the correct variant and filter the gallery on the same render cycle as the page load. It does all of this without requiring any theme code edits, manual insertion of JavaScript, or CSS hacks.
This post is part of 3 posts on how we handle Instant pages for Rubik, how to set it up, and a few small fixes for edge cases where the first install isn’t quite 100% perfect.
In this post
- Why Instant pages need a special detection module
- How Rubik detects Instant product sections
- Setup in 4 steps
- Manual, AI, or bulk assign on Instant stores
- Common issues and fixes
- Frequently asked questions
- Related reading
Why Instant pages need a special detection module
Variants image apps generally hardcode selectors to find the gallery, variant picker, or options on a product page. These apps typically hardcode classes to find the gallery or a specific event on the variant picker. They also hardcode the structure of the options list. Most page builders on the market (including Elementor, Beaver Builder, Visual Composer and others) replace standard product content with custom blocks instead of galleries or options lists. As a result these apps will load correctly but will essentially do nothing.
Instant builds product pages out of its own components. The gallery is an Instant gallery component and the variant picker is an Instant option block. A generic app might find the picker though and it is likely to try to filter the gallery but the gallery isn’t there. So nothing happens when a customer clicks blue. They will only see the wrong image too. They’ll assume the colour they wanted is out of stock and leave.
That’s the penalty of using a generic variant image app on a page builder. Compared to other apps that know what Instant looks like, this fix isn’t even that different.
How Rubik detects Instant product sections
Variants are detected using 8 different methods on every product page load. One of these is Instant, which Rubik will switch into if it finds Instant markers (asset URL, section ID, block class patterns) in the DOM on load. Once in Instant mode, the script uses Instant-aware selectors for the gallery, variant picker, and click handlers.
This is fast because Rubik is metafield-based. There’s no need to wait for external calls while rendering with Instant. The variant-to-image map is stored in product metafields, loaded when rendering the page. When the page is rendered by Instant, Rubik reads the metafields, matches them to the gallery, and filters within the same render cycle. No flicker, no shift, and no second network round trip.
It handles both store pages with the default theme and Instant pages. It checks on each product page for the existence of its state and dynamically changes. No switches to flip, no configuration per page.
Setup in 4 steps
- Install Rubik Variant Images from the Shopify App Store. Free plan covers 1 product, which is enough to test on a single Instant page.
- Enable the Rubik app embed in your active theme. Online Store, Themes, Customize, App embeds. Toggle Rubik on, save. Instant pages still rely on the theme app embed system, so this step is required even if Instant renders the layout.
- Open the product in Rubik and assign images to variants. Three options: manual per-variant, AI auto-assign on a single product, or bulk assign across hundreds of products at once.
- Open the Instant product page on the storefront and click a swatch. The gallery should filter to that variant’s images instantly. If it does not, see the issues section below.
Manual, AI, or bulk assign on Instant stores
Rubik offers several methods for mapping images to product variants – you can choose the best method for your catalogue size.
Manual assign is great for small product catalogues or a specific product that may require different gallery rules. In Rubik, you open up the product and select the individual variant, then assign the relevant images to that variant within the product in about 30 seconds per variant. Good for hand-curating a very small store.
AI has an AI powered run assignment feature that works on a single product at a time. It can automatically assign runs based on 4 data fields (product name, variant name, image filename and image alt text). This is useful for stores with descriptive file names like “red-front.jpg” and “red-back.jpg” but you do not want to manually assign the 12 different colours to variants via Claude.
Bulk assign is my go-to method for this. It will assign all images in the correct order based off of the Shopify gallery and ensure that the featured image separates out the different variants. There is no filename matching with this method or reliance on AI to pre-order images for you. It simply looks at the galleries in Shopify in bulk and assigns images based off of the order. This is very fast and can bulk assign images for hundreds of products at once, as long as your catalogue is uploaded in a consistent fashion.
Common issues and fixes
Gallery does not filter on swatch click
check app embed in active theme first. If this is off script will never load on Instant pages. Check in theme customizer, in theme settings, under App embeds looking for the Rubik’s entry.
Make sure you assigned images in Rubik for this display. If you didn’t assign anything, there is nothing to filter. Check the product and its variants in Rubik for a minimum of 1 image assigned.
Two variant pickers showing on the page
This bug occurs when the Instant page loads with an theme product section imported IN ADDITION to an Instant variant block. Customer clicks one but Rubik picks the other. Open Instant editor and remove the duplicate picker. One Instant page should have one picker only.
Wrong image on first paint
Set the variant’s first image as the product’s featured image in Shopify admin. Even with metafield-based loading, the first paint comes from whatever Shopify ships as the featured image. Match it to the default variant and the issue goes away.
Mobile gallery behaves differently from desktop
Instant also supports different blocks for mobile and desktop versions of your store layout. It’s possible that a different gallery component will require a separate detection pattern. Please inform the Rubik team of your store URL and we will add detection for the specific block you need.
Why Instant merchants pick Rubik
Instant users care about page speed. That is the whole reason they picked a clean modern builder. So a variant image app that adds external API calls on every page load defeats the purpose. Rubik is metafield-based with no external API calls. The data ships with the page. Speed scores stay where they were.
Cool. You can also read that 10 year old Rubik also is a Shopify App, has 5.0 stars with 343 + reviews on the App Store and has flat pricing – Free for 1 product, $25/month for 100, $50/month for 1000 products, and $75 for unlimited. Free for 1 product, $25/month for 100, $50/month for 1000 products, and $75 for unlimited. No Shopify-plan surcharges. No surprise upgrades when your store grows.
Frequently asked questions
Does Rubik Variant Images work with Instant page builder?
Yes. Rubik has a built-in Instant detection feature which identifies the Instant product sections and also instantly filters gallery content on variant click without requiring any additional code.
Do I need to edit code to make Rubik work with Instant?
Setting Enable the Rubik app embed in your theme. Setting images in the Rubik admin. The rest is automatic.
Does Rubik affect page speed on Instant pages?
No. The engine uses metafield data instead of an external API, and all variant data is included in the initial page load with no additional calls.
Can I use colour swatches with Instant?
Yes. Custom variant swatches such as circle, square, pill, image and button can also be added to the variant picker on Instant product pages and can be styled in the Rubik admin.
What if some pages use Instant and others use my theme?
Rubik is per page adapt on the fly. It checks every product page on load for its unique dimensions and content and adjusts on the fly to fit perfectly. This means pages that load instantly will have Instant detection rules created. Meanwhile pages in the theme will have special theme rules created to make sure Rubik scans everything optimally.
Does Rubik work on Instant collection pages?
No . Rubik Variant Images is product page only. For collection page swatches and grouping separate products, use Rubik Combined Listings. variant image styles.
How is Rubik priced?
Flat pricing. Free for 1 product, Starter $25/month for 100 products, Advanced $50/month for 1000, Premium $75/month for unlimited. No Shopify plan surcharges.
Related reading
