Why most themes need an app for this, and this one does not
Shopify already knows what colour your Sand t-shirt is. It stores it as a colour-pattern metaobject linked to the colour option on the product, and it is real structured data — a colour, a name, and a reference into Shopify's own colour taxonomy.
Most themes do not read it. So the swatch apps exist to store a second copy of the same information, inside the app, which the merchant then maintains by hand. Two copies of the truth, a monthly fee for the second one, and a script on your storefront to render it.
Hullara reads the first copy. There is no app, no hex code typed into a theme setting, and no second list to keep in step. The consequence worth caring about is not the saved subscription — it is that a swatch cannot disagree with the variant it selects, because there is only one place the colour is written down.
Where they appear
Two places, from one setting:
- The product page, in the variant picker, as the way a shopper chooses.
- The collection card, so a shopper scanning a grid can see that a product comes in five colours before clicking into it.
The setting itself offers three modes — swatch only, swatch with the colour name, or the name alone. Which you want depends on your palette: five clearly distinct colours read fine as circles, while four shades of off-white need their names.
Neither mode will invent a colour
If an option value has no colour data behind it, Hullara renders its name, not a placeholder circle.
That is a deliberate refusal and it is the same principle as the rest of the theme. The obvious alternative is to fall back to grey, which produces a row of identical grey discs where a shopper cannot tell Sand from Stone from Bone — the picker looks finished and communicates nothing. A name is less pretty and it works.
The four things that have to be true, which no error message will tell you
This is written down because it cost real time to establish, and because if your swatches are not rendering, the reason is almost certainly one of these — and Shopify's API will not name it.
One — the metaobject type has two hyphens. It is shopify--color-pattern.
The dotted form that appears everywhere human-facing, shopify.color-pattern, is
RECORD_NOT_FOUND through the API.
Two — the color field holds one colour, not a list. A pattern with several
colours is a different thing; a swatch is one.
Three — both taxonomy references are required. color_taxonomy_reference and
pattern_taxonomy_reference are not optional, so an entry with only a hex value
is rejected as "Base color can't be blank" — an error that names the colour and
never mentions the missing reference. What the fields actually take is in the
next section.
Four — and this is the one that costs the most time — a product with no taxonomy category cannot hold a swatch at all. Colour-pattern is a category metafield. An uncategorised product rejects every colour you send it as "invalid", and the error names the value rather than the category, so it reads like a problem with your colours. It is not. Set the product's type from Shopify's taxonomy and the identical values are accepted.
We established that last one by sending two byte-identical requests, one to a categorised product and one to an uncategorised product, and reading the difference. Every product in both of Hullara's demo catalogues now names its full taxonomy path, resolved against Shopify live and matched exactly — because searching the taxonomy for "T-Shirts" returns children's clothing first.
One more, if you are writing this yourself: productSet cannot link an option
to a metaobject. That is productOptionUpdate, with the ids in
optionValuesToUpdate rather than in linkedMetafield. Nothing in the error for
the first call points at the second one.
The "Base color" field, for developers
If you arrived here from "Base color can't be blank", this is the section you
want. The admin calls the field Base color; the API calls it
color_taxonomy_reference, and there is no field named base_color to set.
A shopify--color-pattern entry has three fields that matter:
color— one hex. The colour a swatch draws.color_taxonomy_reference— the Base color. A list of one to four values from Shopify's colour taxonomy, not a hex and not a single value. A two-tone value keeps both of its colours here, even thoughcolorkeeps one.pattern_taxonomy_reference— one value from the pattern taxonomy, such as Solid. Required, with no default.
The taxonomy values are ids, not names. Shopify's colour attribute is
gid://shopify/TaxonomyAttribute/1 and pattern is
gid://shopify/TaxonomyAttribute/3; query both with nodes and their values
give every id you can use. This is the shape of the fields in metaobjectUpsert
that Hullara's own demo catalogue is created with — the colour Bone, whose Base
color is the taxonomy's Beige and whose pattern is Solid:
{
"type": "shopify--color-pattern",
"fields": [
{ "key": "color", "value": "#e6e0d4" },
{ "key": "color_taxonomy_reference", "value": "[\"<id of Beige>\"]" },
{ "key": "pattern_taxonomy_reference", "value": "<id of Solid>" }
]
}
The list goes in as a JSON-encoded string, as the seed sends it. Send only
color and every entry comes back as "Base color can't be blank".
On the storefront side you never read the metaobject directly. Once an option is
linked to it (with productOptionUpdate, above), Shopify fills
product_option_value.swatch for each value, and a theme reads that:
{%- for value in option.values -%}
{%- if value.swatch.color != blank or value.swatch.image != blank -%}
<span style="--swatch-color: {{ value.swatch.color }}"></span>
{%- else -%}
{{ value.name }}
{%- endif -%}
{%- endfor -%}
That fallback to the name is the same rule Hullara follows, for the reason given above. If you install themes for clients and would rather not write this yourself, the partner programme gives you a free test licence for a development store.
What this does not do
It does not generate colours from your product images, and it does not guess. If Shopify does not hold a colour for a variant, the theme shows the name. If you want a swatch, the colour goes into Shopify — where your other systems can read it too, which is the point of putting it there rather than in a theme setting.
It also does not show a pattern or a texture image per variant. That is a different feature and it is not here.
Which edition
Both. Swatches are part of the product page in Core and in Pro — this is not a Pro feature. The full section and block list for each edition is on the pricing page, generated from the theme's own build rather than typed out, so it cannot promise you something the zip does not contain.
Swatches are one of several product-page jobs a store usually installs an app for. The others in every edition each have a page with tested code for Dawn and Horizon: a size chart, a sticky add-to-cart bar and a free-shipping bar. The full list is on the features page.