Shopify Product Variants in Framer: Swatches, Stock, URLs
Shopify product variants are the per-option versions of a single product — a size, a colour, a material — and each one carries its own price, image, SKU and stock. On a Framer product page, you load every variant with the product, then let the selector swap price, image and availability while tracking the variant ID that add to cart actually needs. Give each combination a URL parameter so a shopper can link to it and a crawler can index it.
That last job is where most custom product pages fall over. A Liquid theme does variant switching for you. Design the page in Framer and you own the whole mechanism — which is more control, and more to get wrong.
What counts as an option and what counts as a variant
An option is the axis: Colour, Size, Material. A variant is one point on that grid. Shopify's documentation puts it plainly — "each combination of option values for a product can be a variant for that product". Three options with five values each is 125 variants, and every one is a separate object with its own price, barcode and inventory count.
Keep the distinction straight, because the API does. The Storefront API's ProductVariant object exposes selectedOptions (the option values that define this variant), price, availableForSale, quantityAvailable and image. A Shopify product options app sells you a selector; what you need on a Framer page is those five fields wired to five pieces of the interface.
Why do variant selectors break outside a Liquid theme?
Because the theme was quietly doing three jobs, and only one of them is visible. It rendered the selector, it kept per-variant state, and it rewrote the hidden variant ID the form submits. Rebuild only the first and the page looks right while the cart receives whatever variant loaded first.
The Shopify developer community has a long-running thread on the related problem of determining the default displayed variant without Liquid — a reminder that "which variant is selected right now" is application state you have to hold deliberately, not something the markup tells you.
One detail catches teams late: variant metafields. Shopify states that "at this time, product variant metafields can't be displayed to customers", so any per-variant copy you were planning to pull from a metafield needs another home.
Can you have unlimited Shopify variants?
No, and the ceiling is not the number most guides quote. Shopify's merchandising documentation states you can request up to 2,048 variants in one request using the first argument on the variants connection, that productVariantsBulkCreate accepts up to 2,048 variants in a single operation, and that deletes are capped at 250 at a time.
The genuine per-store limit is not a printed figure at all. It lives on the shop object as maxProductVariants and maxProductOptions, both returned as integers. If a catalogue is anywhere near the edge, query the store rather than trusting a blog post — including this one.
Shopify product variants checklist: Liquid theme vs Framer page
Seven behaviours have to survive the move. Here is who handles each one, and the field or limit to watch.
| Behaviour | In a Liquid theme | On a Framer page | Field or limit |
|---|---|---|---|
| Price updates on selection | Theme JS reads the variant array | You bind the selected variant's price to the price node | price (MoneyV2) |
| Variant image swap | Theme pairs media to variants | Your selector sets the gallery's active image | image, falls back to product image |
| Sold-out state per option value | Theme greys out the value | You compute availability per value from all variants | availableForSale |
| Combinations that do not exist | Theme hides or disables them | You mark them unselectable before the click | up to 2,048 variants per query |
| Default selection on page load | Theme picks the first available | You choose it explicitly on mount | first variant where availableForSale is true |
| Deep link and canonical URL | Theme reads the variant query param |
You write and read your own params | 1 param per option (Shopify's default style) |
| Variant ID at add to cart | Theme rewrites a hidden input | You pass the selected ID to the cart call | variant ID, not product ID |
The row that costs real money is the last one. Price and swatch errors look wrong; a stale add-to-cart ID sells the wrong thing or nothing at all.
Should each Shopify variant get its own URL?
Yes — a shopper should be able to send someone the blue one. Shopify's own front-end framework settles the format. Its variant selection documentation describes two URL styles and names the default:
The default options style writes one param per option. — Shopify, Hydrogen variant selection documentation
The same page documents a second style that "writes a single numeric variant ID param for shareable links", and notes that Shopify's route handler redirects those variant links back to option param URLs. The practical read for a Framer build: write human-readable option params such as ?Color=Red&Size=M, accept a legacy variant= ID if one arrives, and keep one canonical URL for the product so the Shopify variant URL pattern does not fragment your indexing. Our guide to Framer SEO for product pages covers the canonical and schema side of that in detail.
Getting the selector shipped
Build the grid before the visuals. List every option, every value, and which combinations genuinely exist, then decide the default and the sold-out behaviour — those four decisions determine whether colour swatches feel instant or feel broken. Only then design the swatches.
Pulling live variant data into Framer is the part FramerLink handles: products, options, prices and stock sync into the page so the selector reads real values instead of a hard-coded list. From there the same pattern extends across the storefront — the Shopify product page template for Framer shows the full page structure, and collection page design covers showing variant swatches on cards without loading every variant for every product.
Variants are the one place where a beautiful product page and a working one come apart. Get the seven behaviours above right and the rest of the page is just design.
Frequently asked questions
What is the difference between Shopify options and variants?
An option is the axis — Colour, Size, Material. A variant is one point on that grid. Shopify creates a variant for each combination of option values, and every variant carries its own price, SKU, image and inventory count. Three options with five values each produces 125 separate variants.
How do you add variants to a Shopify product?
In the Shopify admin, open the product, scroll to the Variants section and add an option such as Colour or Size, then enter its values. Shopify generates a variant row for every combination, where you set price, SKU, barcode, inventory and the image shown for that variant.
Can each Shopify variant have its own image?
Yes. Each variant can be assigned an image from the product's media library. In the Storefront API the variant's image field falls back to the product image when no variant image is set, so a selector that reads it will never render an empty slot.
Why is add to cart not working after selecting a variant?
Almost always because the button is still holding the first variant ID rather than the selected one. The selector updated the price and image in the interface but never rewrote the ID passed to the cart, so Shopify receives a stale or unavailable variant and rejects the line item.
Sources
- Product variants — Shopify Help Center
- Products and collections — Shopify Developer Documentation
- ProductVariant object, Storefront API — Shopify Developer Documentation
- Variant selection — Shopify Developer Documentation
- ShopResourceLimits object, Admin API — Shopify Developer Documentation