Badges
Badges are visual indicators displayed on product cards and product pages to communicate product status, promotions, and special attributes to customers.
Badge Typesโ
The badge system uses three types of badges:
| Badge Type | Description | Used On |
|---|---|---|
| Pill Badge | Pill-shaped badge with colored background | PDP only |
| Text Badge | Text-only badge for status/promos | PDP and PLP |
| Image Badge | Badge overlaid on product image | PLP only |
Badge System Architectureโ
The badge system is split across two repositories depending on the page context:
| Context | Repository | Framework | Rendering |
|---|---|---|---|
| Product Listing Pages (PLP) | static-assets | SearchSpring | Server-side (afterStore hook) |
| Product Detail Pages (PDP) | hydrogen-storefront | React/Remix | Client-side components |
Badge Display Limitsโ
| Page | Badge Type | Max Count | Location |
|---|---|---|---|
| PLP | Text Badge | 1 | Below product details |
| PLP | Image Badge | 1 | Top-left of product image |
| PLP Total | 2 | ||
| PDP | Pill Badge | 2 | Top of product info |
| PDP | Text Badge (subtitle) | 1 | Below subtitle |
| PDP | Text Badge (final sale) | 1 | By price (top right) |
| PDP Total | 4 |
Note: Image Badges (Ships Now, Personalize) share the same position, so only 1 displays. Subtitle Text Badges (oos/firstswatches/promo) are mutually exclusive scenarios.
Badge Locationsโ
PDPโ
PDP badges render in three distinct areas:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ [Pill Badge] [Pill Badge] โ โ Top of product info (max 2)
โ โ
โ Product Title โ
โ Subtitle โ
โ [Text Badge] โ โ Below subtitle (1 of: oos/firstswatches/promo)
โ โ
โ $99 โ
โ [Final Sale] โ โ Text Badge by price
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
PLPโ
PLP badges render in two distinct areas:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ [Image Badge] โ โ โ Top-left of image (Ships Now or Personalize)
โ โ โ โ
โ โ Product Image โ โ
โ โ โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ Product Title โ
โ Subtitle โ
โ $99 โ
โ [Text Badge] โ โ Below product details (max 1)
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Shared Tag Patternsโ
Some tags trigger badges on both PLP and PDP:
| Tag | PLP Badge | PDP Badge |
|---|---|---|
'badge:eoy25clearance' | EOY Sale Text Badge | EOY Sale Pill Badge |
'badge:lightningdeal' | Lightning Deal Text Badge | Lightning Deal Text Badge |
'Best Seller' | Best Seller Text Badge | Best Seller Pill Badge |
'New Arrival' | New Arrival Text Badge | New Arrival Pill Badge |
'finalsale' | โ | Final Sale Text Badge |
'personalizable' | Personalize Image Badge | โ (uses metafield) |
Related Documentationโ
- PLP Badges - Badge display on Product Listing Pages (priority system, image badges, SearchSpring data)
- PDP Badges - Badge display on Product Detail Pages (Pill Badges, Text Badges, Shopify data)