Metafields

A few Peregrine features read extra information you store against a product — a metafield. This chapter explains what that means, why you have to create them yourself, and how to set up each one.

What a metafield is, and why the theme can't create it

A metafield is an extra field you add to a product beyond the built-in ones — an image, a piece of text, a file. You create the definition once in your admin, and from then on every product has that field ready to fill in.

Peregrine can read metafields, but no theme can create them. A Shopify theme is presentation only — it has no access to your admin and no installer that runs when you add it, so it cannot add fields to your products. Only you, or an app you've given permission to, can do that. Every theme on the Shopify Theme Store works this way.

The practical upshot is simple: a metafield feature does nothing until you create the definition. That is not a fault — it's the normal state of a fresh install, and Peregrine is built for it. Every metafield-driven feature falls back to an ordinary setting, so nothing looks broken or empty while you decide whether you want it.

You only do this once per feature. Creating a definition takes about a minute. After that the field appears on every product, and you fill it in only on the products you want it on.

One feature is an exception, and it's worth knowing why. The "Goes well with" block also reads a metafield, but you never create it: Shopify's own free Search & Discovery app creates and maintains it for you when you choose complementary products. Nothing in this chapter applies to it — install the app, pick the products, done. Where an app already owns a field, Peregrine reads that rather than asking you to build a second one.

Creating a definition — the general steps

In Shopify admin go to Settings → Custom data.
Under Metafield definitions, choose Products.
Click Add definition.
Give it a name — this is the label you'll see on the product page, so make it obvious, e.g. "Button background".
Check the namespace and key Shopify generates underneath the name. That's the technical identifier, written as namespace.key — for example custom.button_background. You'll need it in a moment.
Choose the type the feature needs (each feature below tells you which), then Save.

The field now appears at the bottom of every product's page in admin, under Metafields.

Add to cart button — per-product colours

Your Add to cart button is styled once for the whole store in Theme settings → Add to cart buttons, and that is where it should be set. This is the escape hatch for the handful of products that genuinely need to look different — a limited edition, a clearance line, a collaboration with its own brand colours.

Set only the ones you want to change. Each metafield you fill in overrides that one thing for that one product; everything you leave empty carries on following your theme settings. A product with none of these set looks exactly as your theme says, which is the case for almost every product in almost every store.

1. Create the definitions

Six definitions, all on Products, all created the same way — Settings → Custom data → Products → Add definition. You only need the ones you actually intend to use; skip the rest and come back later if you change your mind.

What it changes	Namespace and key	Type
Button colour	`custom.button_color`	Color
Button text colour	`custom.button_text_color`	Color
Hover colour	`custom.button_hover_color`	Color
Hover text colour	`custom.button_hover_text_color`	Color
Border width, in pixels	`custom.button_border_width`	Integer
Border colour	`custom.button_border_color`	Color

The keys must match exactly. Shopify suggests a key from the name you type, and a spelling that differs from the table — button_colour instead of button_color, say — is the single most common reason one of these appears to do nothing. It fails silently: the product just keeps using your theme colours. Check each key against the table before saving.

For Integer, set the validation to a sensible range — minimum 0, maximum 6 — so nobody types 400 and buries the label under a border. For each Color definition, "One value" is the right choice.

2. Check the namespace matches the theme

In the theme editor, open a product template, select the Buy buttons block and look at Metafield namespace. It's pre-filled with custom, which is what Shopify gives you by default — so if you accepted the suggested namespace in step 1, there is nothing to do here.

Change it only if your store keeps its metafields somewhere else. The theme reads all six keys from whichever namespace this names.

3. Set them on a product

Open the product in Shopify admin.
Scroll to Metafields at the very bottom of the page — you may need to click Show all.
Fill in only the fields you want to change for this product. A colour field gives you a picker; the border width takes a plain number.
Save, then view the product on your storefront.

To put a product back to normal, clear the fields again — an empty metafield is the same as never having set one.

What it looks like in practice

Say your store's buttons are black, and you want one product's button in your brand's green with white text. Set custom.button_color to the green and custom.button_text_color to white on that product, and leave the other four empty. That product's button turns green; its border, hover and everything else still follow your theme settings, and every other product in the store is untouched.

If a colour doesn't take effect

Check the key spelling, especially color vs colour. This is nearly always it.
Check the namespace in the Buy buttons block matches the one on your definition.
Check the type — a colour saved as a text field won't be read.
Check you saved the product, not just the definition.

These override the product page's Add to cart button. The Add buttons on collection and search cards always follow your theme settings — a grid of cards where each button is a different colour would read as broken rather than special.

Buy button background image

Give an individual product its own add-to-cart button background image, instead of a flat colour. Useful when a product has strong artwork of its own, or for a limited-edition line you want to stand out in a catalogue that otherwise shares one button style.

1. Create the definition

Field	Value
Name	Button background (or whatever you like)
Namespace and key	`custom.button_background`
Type	File, then limit it to images
Number of values	One value

Choosing the File type is what gives you an image picker on the product, so you select from your Files library rather than pasting a link.

2. Point the block at it

In the theme editor, open your product template, select the Buy buttons block, and find Background image (per product). The Metafield field is pre-filled with custom.button_background — if you used a different namespace or key in step 1, change it here to match exactly.

3. Set an image on a product

Open any product in admin, scroll to Metafields at the bottom, and select an image for the field. Save, and that product's add-to-cart button now uses it. Leave it empty on every other product.

How it decides what to show

The image simply wins when it's there — there's no switch to remember:

The product has an image in the metafield → the button uses it.
It doesn't → the button uses the background, text and border colours set on the Buy buttons block.
Those are left blank → the button follows your theme palette, like every other button.

Overlay strength — don't skip this

Peregrine tints the image with your button colour before drawing the label on top, at an Overlay strength you control (40% by default). This is not decoration. Button text sitting directly on a photograph is very often unreadable, and unreadable button text is an accessibility failure that will be flagged in a Shopify theme review — as well as costing you sales from people who simply can't see the button.

Leave it near the default for photographic or busy images.
Lower it for a flat brand texture or a subtle gradient, where the label stays legible anyway.
Set it to 0 only after checking the button on a phone, in daylight. If you can't read it instantly, put the overlay back.

Whatever you choose, set the Text colour on the block to something with real contrast against your image — white on a dark image, near-black on a light one.

If the image doesn't appear

Check the key matches exactly. The Metafield field in the block and the namespace/key in your definition must be identical, including the dot — custom.button_background, not custom.Button_Background.
Check the type is File, limited to images. A text or URL field won't render; the theme is looking for a real file.
Check you set the image on the product you're looking at, not on a different one. This is per-product by design.
Check the product saved after you picked the image.

More to come

Further metafield-driven features — product ratings from a review app, manufacturer part numbers, and bundle definitions shared with our Stackmate app — will be documented here as they ship. Each one follows the same shape: you create the definition, you tell the theme its key, and the feature stays silently out of the way until you do.