Badges setup

Product badges highlight what's new, what's on sale, what's running low, and any custom message you want shoppers to see at a glance. Uisce has two badge systems:

• Product page — the tag / metafield badges this guide covers, rendered above the product title. You declare them per product.
• Product cards (collection / homepage grids) — automatic badges the theme derives from product state: sold out, pre-order, sale, low stock, and new. Nothing in this guide configures them.

This guide walks you through wiring the product-page badges using either tags (simplest, works on day one) or metafields (explicit, supports bulk editing). You can mix both — the theme unions the two sources and de-duplicates by type.

TIP

This theme is Shopify Theme Store compliant and does not ship a metaobject definition for badges. You create the metafield definition yourself in a few clicks — instructions below.

Overview

Surface	Source	Max badges visible	Notes
Product page hero	Tags + metafield (this guide)	3	Horizontal row immediately above the product title. Overflow shows a +N pill.
Product card	Automatic (product state)	2	Sold out, pre-order, sale, low stock, new — in that priority. Driven by inventory, price, the uisce.preorder / uisce.low_stock metafields, and a new tag; not configured through this guide.

Uisce also ships a Badge theme block (blocks/badge.liquid) that you can compose inside any section that accepts @theme blocks — handy for video-hero overlays or banner callouts.

Tag-driven badges

Add a tag to any product to render a badge automatically. The theme matches tags case-insensitively.

Tag conventions

• badge:<type> — renders a badge whose visible label is the translated value for products.badges.<type>. The theme ships that key for new, sale, low_stock, and out_of_stock in all 50 locales; any other handle needs its own locale key (see Custom badge labels).
• badge:<type>:<value> — same as above; the :value suffix is parsed but ignored for label rendering.

Tags are downcased before lookup, so capitalisation never matters — badge:New and badge:new are the same type. Underscores and hyphens are not interchangeable, though: use the underscore form that matches the shipped key (badge:low_stock); badge:low-stock is a different, custom type with no shipped label.

Examples

• badge:new — renders "New"
• badge:sale — renders "Sale"
• badge:sale:30 — renders "Sale" (the :30 is parsed but not rendered in the label)
• badge:low_stock — renders "Low stock"
• badge:bestseller — merchant-defined custom type; add a products.badges.bestseller locale key for its label

Custom badge labels

Any handle outside the shipped four (new, sale, low_stock, out_of_stock) needs a matching products.badges.<handle> key in your locale files, or the badge renders a missing-translation label instead of readable text. Add the key under products.badges in locales/en.default.json (Online Store → Themes → Edit code → locales/) — and in every other locale you sell in. See the Translations guide.

Where to set tags

Shopify Admin → Products → your product → Tags field in the right-hand column. Save the product. The badge appears on the storefront immediately.

Metafield-driven badges

Use a metafield when you want explicit control, bulk editing through Shopify's Bulk Editor, or when your badge handles shouldn't pollute the product tag list (tags affect search and collection rules too).

Product metafield definition

1. Shopify Admin → Settings → Custom data → Products → Add definition.
2. Name: Badges
3. Namespace and key: uisce · badges (type these in the "Advanced — namespace and key" field; the namespace must be uisce and the key must be badges for the theme to pick it up).
4. Type: pick List of: single line text.
5. Validations: (optional) restrict to a list of accepted values such as new, sale, low_stock, bestseller, certified_organic.
6. Save the definition.

Populating values

On any product page, scroll to Metafields at the bottom and set the Badges list. Each entry is a handle — no spaces, lowercase, underscores for multi-word types (matching the products.badges.<handle> key). Unlike tags, metafield entries are used exactly as typed, so keep them lowercase. Example values:

["new", "sale", "bestseller"]

The theme looks up each handle against products.badges.<handle> in your storefront locale. The shipped keys are new, sale, low_stock, and out_of_stock; add a locale key for any other handle (see Custom badge labels).

Bulk editing

In Shopify Admin → Products → Bulk edit, add the Badges (uisce.badges) column. Paste comma-separated handles into the cells. Shopify handles the conversion to the list format.

Collection scope filter

By default, a product's badges render on every storefront surface that displays the product. If you want a collection page to show a curated subset (e.g. the "Clearance" collection should show only sale badges), add a scope metafield to the collection.

Collection metafield definition

1. Shopify Admin → Settings → Custom data → Collections → Add definition.
2. Name: Allowed badges
3. Namespace and key: uisce · allowed_badges.
4. Type: pick List of: single line text.
5. Save.

On the collection, populate the list with the handles you want to allow. Any badge handle not in the list will be hidden on products viewed through that collection. Leave the list empty to allow all badges (default behaviour).

Marker style

The badge theme block (blocks/badge.liquid) — composable into any section that accepts @theme blocks — has a per-block Marker style setting with three options:

Value	Appearance
solid-circle	Rounded pill (default — highest contrast)
pin-down	Rounded rectangle with a solid fill
tag-shape	Outlined rounded rectangle with a transparent fill

The tag / metafield badges rendered automatically on the product page hero (via snippets/product-badge-list.liquid) always use solid-circle; there is no theme setting to change that shape. Product-card automatic badges carry their own fixed styling.

Badge colours are derived from the section's accent colour. To adjust badge colours across a section, change the Accent colour for the relevant colour scheme under Theme settings > Colors.

Stacking and order

On the product page, the theme caps visible tag / metafield badges at 3; when a product declares more, a +N pill renders after the last visible badge. There is no priority reordering — badges render in the order you declared them: metafield entries first (in list order), then tag-derived entries (in tag order).

Product-card automatic badges are separate: they cap at 2 and follow a fixed priority — sold out, then pre-order, then sale, then low stock, then new.

Conflict resolution

When a product has the same badge type in both a tag and the metafield (e.g. badge:new tag and new in uisce.badges), the metafield-declared entry wins. This is deliberate — the metafield is the "explicit" channel and should override.

Collection scope is applied after the tag + metafield union, so a badge rejected by the collection filter is invisible regardless of how it was declared.

Theme Store compliance

Per Shopify Theme Store rules, themes cannot ship custom metaobject definitions or pre-configured metafield definitions. Uisce follows this rule: the Badges and Allowed badges definitions above are things you create once in your Shopify Admin — the theme only reads their values.

If you see documentation elsewhere suggesting a theme ships badge definitions automatically, that theme is in violation of Shopify policy. Uisce does not do this.

Troubleshooting

• Badge not rendering the right label: check that the handle matches the translation key — underscores, not hyphens (e.g. low_stock). Tags are downcased automatically, so badge:Low_Stock still matches products.badges.low_stock, but badge:low-stock is a different custom type with no shipped label. Metafield entries are used as typed — keep them lowercase.
• Wrong text: add a translation override under products.badges.<handle> in your storefront locale file. See Translations guide.
• Badge on wrong collection: check the collection's uisce.allowed_badges metafield — if it's non-empty, only handles in the list render.
• Multiple identical badges: possible when both a tag and metafield declare the same handle. The metafield wins; the tag entry is de-duplicated. If you see two rendering, report it as a bug.