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 renders badges on three surfaces: the product card overlay (collection / homepage grids), above the title on the product page, and inside predictive search results.

This guide walks you through wiring 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	Max badges visible	Notes
Product card	2 on mobile, 3 on tablet+	Overflow shows a +N pill. Absolute-positioned overlay.
Product page hero	3	Horizontal row immediately above the product title.
Predictive search	2	Compact 12-px-tall variant. Server-rendered results only.

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> (or the tag handle capitalised if no translation exists).
• badge:<type>:<value> — same as above; the :value suffix is reserved for future per-tag data (e.g. percentage) and is currently ignored for label rendering.

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 — renders "Bestseller" (merchant-defined handle)

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, hyphens allowed. Example values:

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

The theme looks up each handle against products.badges.<handle> in your storefront locale; if no translation exists, the handle is capitalised and rendered as-is.

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	Shopping-tag shape with straight corners
tag-shape	Rectangular outlined tag

The marker style for badges rendered automatically on product cards and the product page hero (via snippets/product-badge-list.liquid) uses the theme default — solid-circle. This shape cannot currently be changed via theme settings.

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 priority

The theme caps visible badges at 3 per product (2 in predictive search). When a product has more badges than the placement allows, a +N pill renders after the last visible badge. The default priority order (highest wins a visible slot first):

1. Out of stock / error
2. Sale / warning
3. New / success
4. Low stock / warning
5. Any merchant-defined custom badges

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: check that the tag or metafield handle is lowercase and uses hyphens (not underscores). Handles like Low_Stock or LowStock won't match the default products.badges.low_stock translation key and will render capitalised raw.
• 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.