Swatch King can show product options on the grid product cards across your collection pages, search results, carousels and other grids. Collection page settings is where you choose how each option appears there — or whether it appears at all.
When a shopper selects a color on a product card, the card's image, price and theme badges update with it, so they can compare variants without opening the product.
Before you start: check your Page settings
Grid swatches are delivered separately from your product page swatches. If the grid options in App settings → Page settings are switched off, nothing on this page will take effect — no grid swatches will appear anywhere on your store.
If your collection page swatches are not showing at all, check there first.
How it fits together
Setting up an option takes up to three decisions, and the later ones only appear when they apply:
Pick a style — swatch, button or dropdown — or choose Do not show to keep the option off your grids
If you picked a swatch style, pick a swatch source — what the swatch actually shows
If you picked Color/custom image as the source, upload the colors or images
That covers which options appear and what they look like. Where they sit on the card, and whether they respond to hover, is set in your theme editor — see Where the swatches sit on the card below.
The page has four columns.
Column | What it does |
Option name | Every unique option in your store |
Desktop option style | The style shown on grids on desktop |
Mobile option style | The style shown on grids on mobile |
Upload swatch | Where you add colors and custom images |
Option name
Lists every unique option name across your products — Color, Size, Material and so on.
Options are case sensitive. If one product uses "Color" and another uses "color", they count as two separate options and each needs its own style.
Click in x products under any option name to see which products use it.
Desktop and Mobile option style
These two columns work identically — you set them separately so you can use one style on desktop and a different one on mobile. Grid cards are small, so a compact style usually works better on mobile.
Click the dropdown next to an option to open the Select option style modal.
The modal shows every style in your Customize styles library, plus one extra choice:
Do not show — keeps that option off your grid cards entirely. Useful when Color is worth showing on a card but Size or Material only matters on the product page.
Swatch sources
If you choose a swatch-based style such as Polaroid swatch, a second dropdown appears for the swatch source:
Source | What the swatch shows |
First variant image | The variant's first image |
Second variant image | The variant's second image |
Last variant image | The variant's last image |
Color/custom image | A color or image you upload yourself. Choosing this adds an upload icon in the Upload swatch column |
Button and dropdown styles have no swatch source — there is no image to show.
Upload swatch
The upload icon appears for any option where you set the swatch source to Color/custom image, on desktop or mobile.
Clicking it opens a modal listing every unique value for that option, with a preview of its current color or image. Click x products beside a value to see which products use it.
Three ways to set a swatch:
Add color — pick from the palette or enter a hex code
Add from URL — point to an image already hosted online
Add file — upload an image from your device
Image requirements
PNG, JPG or JPEG only
Under 512kb
If you are adding from a URL, it must be publicly accessible
Already uploaded on the product page? Colors and images you set in Product page settings carry across automatically. You do not need to upload them again here.
Where the swatches sit on the card — and how they behave
Four settings control the placement and behavior of swatches on your product cards. These are not in the app dashboard — they live in your theme editor, inside the Swatch King app embed, because they depend on how your theme builds its product cards.
This is the single most common thing merchants look for in App settings and cannot find. It is here:
From your Shopify admin:
Go to Online Store → Themes
Find the theme you want to edit and click Customize
In the sidebar, click the App embeds icon
Click the expand arrow ▸ beside Swatch King
Swatch alignment
Where the swatch row sits within the card.
Option | Result |
Left | Swatches align to the left of the card |
Center | Swatches sit centered |
Right | Swatches align to the right |
Match this to how your theme aligns its product titles and prices, or the card will look off-balance.
Swatch position
Which part of the card the swatches appear under.
Option | Result |
After image | Directly below the product image, above the title |
After title | Below the product title |
After price | Below the price, at the bottom of the card |
Change variant image on swatch hover
When this is on, hovering over a swatch updates the card's main image to that variant — the shopper does not have to click.
This is available on collection pages only. The same behavior on a product page needs a custom script from our team — send us a message in the chat if you want it there.
Auto-select variant
When this is on, each card loads with its first available variant already selected, and the card's title, price and image update to match it.
These four settings are per theme, and they override the dashboard. If you switch to a different theme, or duplicate your live theme, set them again on the new one. They are also the final word — if a placement looks wrong, this is the screen to check, not the app dashboard.
Bulk operations
For stores with a lot of options, you can work in bulk from the toolbar or by CSV.
Assign styles to several options at once, from the toolbar
Assign styles to several options at once, from the toolbar
Search for options in the search bar, then tick the checkbox beside each one you want to change. With options selected you can set:
Desktop option style
Desktop option swatch
Mobile option style
Mobile option swatch
Assign styles in bulk by CSV
Assign styles in bulk by CSV
Click Bulk update options in the top right, then Export file. You can send the export to your registered email or any other address.
The CSV has six columns:
Column | Values |
Option Name | The option name exactly as it appears on your products |
Collection Page Style Name - Desktop | A style name from your Customize styles library, or Hidden to keep the option off your grids |
Collection Page Swatch Source - Desktop | Custom Swatch, First variant image, Second variant image, or Last variant image — swatch styles only |
Collection Page Style Name - Mobile | As above, for mobile |
Collection Page Swatch Source - Mobile | As above, for mobile |
Manual Option Selection | True or False. True requires the customer to choose this option before adding to cart. This is the same setting as App settings → Option selection |
Note the wording difference. In the dashboard the choice is called Do not show. In the CSV, the value you enter is Hidden. They do the same thing.
Fill it in, then click Import file.
Upload swatch colors and images in bulk by CSV
Upload swatch colors and images in bulk by CSV
Click Bulk update swatches in the top right, then Export file.
The CSV has three columns:
Column | Values |
Option Name | The option you are uploading swatches for |
Option Value | The specific value — Red, Large, Cotton |
Swatch Color Code / Image URL | A hex code, or a public URL to an image under 512kb |
Fill it in, then click Import file.
If your grid swatches aren't showing
Check App settings → Page settings. The grid options must be on for the page types you want — collection and search, home page, product page grids. This is the most common cause by a wide margin.
Check the option isn't set to Do not show on this page.
Check the right view — desktop and mobile styles are set separately, and it's easy to change one and test the other.
Check the app embed is on for your published theme, in App settings → Theme status.
Showing, but in the wrong place on the card? That is Swatch position and Swatch alignment in the theme editor, not the dashboard — see the section above.
If your product pages work but your grids don't after all of that, it is usually that your theme's product cards are built in a way the app doesn't recognize yet. Send us your store URL and a collection page link through the chat — this is quick for us to add support for.
Need help? Our support team is always here. Hit the chat button and we will get you sorted.