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)