Colour swatches

Colour options render as chips rather than text pills — on product cards, in the variant picker, and in quick view. You don’t upload a swatch image for every colourway unless you want to.

Settings

Theme settings → Swatches

Setting	Type	Default	What it does
Swatch option names	Text	color, colour, shade, tint	Comma-separated product option names that render as swatches
Custom swatch colors	Textarea	(empty)	Your own colours, one per line, as Name:#hex or Name:image URL

An option whose name matches swatch_options (case-insensitive, whitespace trimmed) becomes a chip row. Everything else stays a labelled pill. Add your own names if your catalogue uses something else — Finish, Colourway, Dye.

How a colour is resolved

Three stages, in order. The first hit wins.

1. Your swatch map. An exact, case-insensitive match on the option value in swatch_map.

2. The built-in dictionary. Around 130 curated names, covering the whole value exactly — Black, Off White, Rose Gold, Sage Green, Slate Grey, Hunter Green, Espresso, Champagne, Titanium, and so on. Common spelling variants are handled: grey/gray, off-white/offwhite, rose-gold/rosegold.

3. Word fallback. The value is split on spaces and each word checked against a shorter list of base colours, so Faded Olive finds olive and Washed Navy Blue finds navy. Nothing found ends at a neutral #ccc.

That last stage is what keeps a catalogue of poetic colour names from turning into a row of grey squares. It’s a fallback, though — not a substitute for naming the colour properly.

Adding your own colours

One line each in swatch_map:

Clay:#b0653a
Deadstock Olive:#4a5338
Signal Orange:#d56a40

The name is matched against the option value exactly as a shopper sees it, so it must be the same string as the one in the product’s option — Clay, not clay dyed. Case and surrounding whitespace don’t matter.

Tip

Map every colour you sell, even the ones the dictionary already knows. The dictionary’s Navy is a generic navy; your navy is the one on the garment. Taking the hex from the product photograph takes a minute per colourway and is the difference between a chip row that looks designed and one that looks approximated.

Swatch images

A line whose value contains // is treated as an image URL rather than a colour:

Camo Print:https://cdn.shopify.com/s/files/1/…/camo-swatch.jpg
Tie Dye Rust:https://cdn.shopify.com/s/files/1/…/tiedye.png

The image is painted as a cover-fitted, centred background on the chip, with a neutral grey behind it while it loads. This is the answer for prints, heathers, marls and anything else a single hex can’t honestly represent.

Upload the file under Content → Files in admin and copy its URL.

Where swatches show up

Place	Behaviour
Product card	A row of chips under the card, when Theme settings → Product cards → Show color swatches is on
Variant picker	34 px chips, with an accent outline on the selected one
Quick view	Chips read back from the card, so they match exactly

In the variant picker, a chip carries a title attribute with the colour name and a visually hidden label, so the name is available to a screen reader and on hover even though the chip itself is wordless. The selected chip is marked with an outline and an outline offset rather than colour alone, which matters when the colour being selected is itself a shade of the accent.

Sold-out values

Non-swatch option pills — sizes — show unavailability as a diagonal hatch with dimmed text, and stay clickable so a shopper can select a sold-out size and reach the back-in-stock form. Values that resolve to no variant at all are disabled outright.

Caution

Colour swatches don’t get the hatch. They’re marked as unavailable in the markup, but visually a sold-out colourway looks like an available one until the shopper selects it and the button reads Sold out. On a catalogue where individual colourways sell out while others remain, that’s worth knowing when you decide which option comes first.

Note

Signal’s swatches are resolved from option names, not from Shopify’s own swatch settings on product option values. That means they work with no setup at all on an existing catalogue — but it also means admin’s own swatch pickers aren’t the source of truth here. The swatch_map setting is.