Metafields
Metafields let one template give every product its own colors, texts and images. This page lists the metafields Balm reads, with the exact name, key and type to create.
Before you start
The theme cannot create a metafield definition; only you can, in your admin. This is a platform rule: a setting can only be connected to a definition that already exists, with the right type. So the definition always comes first, the connection second, the values third.
- Definitions are created in Settings, Custom data, under Products or Shop.
- Type the Name exactly as listed below. The admin derives the key from the name, in lowercase with underscores, so the key matches on its own. If you rename a definition, check its key before saving: the connection works by key.
- Names are shown in quotation marks here and in the theme editor so you can see where they start and end. The quotation marks are not part of the name.
- The namespace and key are suggestions; the type is not. A setting refuses a definition of the wrong type.
- Every connectable setting repeats the definition it expects in its own help text in the editor.
Per product background colors, step by step
The most common use: one product template, a different background shade on every product.
Step 1. Create the definition (once)
- In your admin, open Settings, Custom data, Products and choose Add definition.
- Name:
Background color
. Namespace and key:custom.background_color. Type: Color. - Save.
Step 2. Connect it to the setting (once)
- In the theme editor, open a product page and select the Product section.
- Set Background mode to Solid color (or Gradient (two colors), or Radial halo; the same idea applies to each of their colors).
- Next to Background color, select the dynamic source icon (a small database symbol) and pick Background color.
- The field now shows the metafield name instead of a swatch. Save.
Step 3. Fill in the values (per product)
- In your admin, open a product and scroll to the Metafields card.
- Set Background color to that product's shade and save. Products you leave empty fall back cleanly, as explained below.
Step 4. Check it
Open two products on the storefront, one with a value and one without. The first shows its own shade, the second falls back. If both look the same, the connection of step 2 was not saved.
For a gradient, repeat step 1 with Background color end
(custom.background_color_end) and connect
it to Gradient end. For a halo, create Accent color
(custom.accent_color) and
connect it to Halo color.
Product metafields
Create these in Settings, Custom data, Products, then connect them with the dynamic source icon next to the setting.
| Name | Namespace and key | Type | Connect it to |
|---|---|---|---|
Background color | custom.background_color | Color | Product: Background color, Gradient start, Base color |
Background color end | custom.background_color_end | Color | Product: Gradient end |
Accent color | custom.accent_color | Color | Product: Halo color |
Overlay color | custom.overlay_color | Color | Product: Overlay color |
Curve color | custom.curve_color | Color | Product: Curve color |
Background image | custom.background_image | File | Product: Background image |
Background media | custom.background_media | File | Product: Vignette image |
Badge label | custom.badge_label | Single line text | Product: Badge text; Badge block: Text; Spinning badge: Text |
Badge background | custom.badge_background | Color | Badge block: Badge background |
Badge text color | custom.badge_text_color | Color | Badge block: Badge text color |
Tagline | custom.tagline | Single line text | Text block: Text. The mega menu Products block shows it under each product when Show product tagline is on in the Header. |
Buy button label | custom.buy_button_label | Single line text | Buy buttons: Add to cart label |
Specs label | custom.specs_label | Single line text | Popup: Trigger label |
Specifications | custom.specifications | Rich text | Popup: Content |
Row heading | custom.row_heading | Single line text | Collapsible row: Heading |
Ingredients | custom.ingredients | Rich text | Collapsible row: Content |
Claim title | custom.claim_title | Single line text | Icon item: Heading |
Claim body | custom.claim_body | Single line text | Icon item: Text |
Claim icon | custom.claim_icon | File | Icon item: Icon image |
Product image | custom.product_image | File | Image block: Image |
Image caption | custom.image_caption | Single line text | Image block: Caption |
Spec label | custom.spec_label | Single line text | Specification: Label |
Net weight | custom.net_weight | Single line text | Specification: Value |
Metafields you type by key
A few settings are plain text fields where you type the namespace.key yourself instead of using the
dynamic source icon.
| Where | What to type | Metafield type |
|---|---|---|
| Product section, Packshot captions: Caption source set to Product metafield (list), then Metafield | custom.media_captions | List of single line text on products. Entry 1 captions media 1, and so on; media without an entry use their alt text. |
| Custom badge metafield on Collection, Search, Featured collection, Product recommendations, Recently viewed, Lookbook and the Badge block | custom.badge_label, or any text metafield | Single line text on products. Shown as the Custom badge. See Product badges. |
| Theme settings, Quick view: Short description metafield | For example custom.short_description | Single line or multi-line text on products. Without it, quick view shows the first paragraph of the description. |
| Compare products, Row block: Product metafield | For example specs.caffeine | Any type that fits the row's Value type. See below. |
Product list metafields
The Products setting of the Product upsell block, of the Complementary products block and of the
cart drawer suggestions can be connected to a product metafield of type Product, set to accept a list of
products. Each product then carries its own hand picked selection, for example Upsell products
with the key
custom.upsell_products. The block's Products come from setting must be on
A manual selection.
Shop metafields
Every other section that paints a background (rich text, featured collection, FAQ, contact, image with text and so on) offers the same Section background settings. Those sections are not tied to a product, so their colors connect to shop metafields, created in Settings, Custom data, Shop. One value then applies storewide, which lets you restyle every connected section at once.
| Name | Namespace and key | Type | Connect it to |
|---|---|---|---|
Background color | shop.background_color | Color | Background color, Gradient start, Base color |
Background color end | shop.background_color_end | Color | Gradient end |
Accent color | shop.accent_color | Color | Halo color |
Overlay color | shop.overlay_color | Color | Overlay color |
Background image | shop.background_image | File | Background image |
Review metafields
The Rating block, the ratings on product cards, in quick view and in Compare products read Shopify's standard review
metafields, reviews.rating (Rating) and reviews.rating_count (Integer). Review apps fill them;
you have nothing to create. Until they are filled, the ratings stay hidden.
Compare products rows
Each Row block of the Compare products section reads one product metafield. Match its Value type to the metafield type:
- Text: single line text, multi-line text, or any value you want printed as it is.
- Number with unit: an integer or decimal, followed by the Unit you type (mg, ml, g). Leave the unit empty for weight, volume and dimension metafields, which carry their own.
- Yes or no: a True or false metafield.
What happens on a product with no value
Nothing breaks and nothing goes blank, which is what lets you fill only the products you care about. A background color that comes back empty falls through, in this order:
- the Fallback background color setting, if you set one;
- otherwise the background of the section's color scheme.
Never connect the fallback color itself to a metafield: it is the safety net. If one end of a gradient is empty, the other end fills the whole wash; if a halo color is empty, the halo is not drawn and the base color stays. Empty text, rich text and image metafields leave their block empty, and blocks that exist only to carry the value (rating, badges, popup, a claim line) hide themselves.
Settings that cannot be connected
Shopify only allows connections on colors, text, rich text, images, videos, links, pages, collections, products and metaobjects. Sliders, checkboxes, dropdowns, the color scheme and Liquid code are fixed for the whole template. When one product needs a different value for one of those, give it a second product template.