> For the complete documentation index, see [llms.txt](https://help.lumintheme.com/lumin-theme-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.lumintheme.com/lumin-theme-documentation/how-to-use-custom-badges-on-product-cards.md).

# How to Use custom badges on product cards

## Badges

> **Boost conversion with visual cues.** Use badges to highlight sales, stock status, and custom product attributes across your storefront.

### Overview

The Badges section provides a sophisticated way to communicate value propositions and urgency to your customers. Beyond standard "Sale" and "Sold Out" indicators, this section allows for deep customization of typography, iconography, and decorative effects like shadows and borders.

By leveraging Shopify Metafields, you can extend these badges to show custom labels (e.g., "Eco-friendly," "Best Seller," or "New Arrival") tailored to specific products, ensuring your customers see the most relevant information during their shopping journey.

### Key Features

* **Dynamic Sale Messages**: Use placeholders to automatically display discount percentages.
* **Custom Metafield Support**: Create up to three unique custom badges per product using "Single line text" metafields.
* **Icon Integration**: Add visual flair with built-in icons or custom image metafields.
* **Precision Styling**: Control corner radius, border thickness, and shadow depth to match your brand identity.
* **Flexible Positioning**: Place badges in any of the four corners of your product imagery.

### Custom Badge Setup (Metafields)

To use custom badges beyond the standard "Sale" and "Sold Out" labels, you must set up specific metafields in your Shopify Admin.

#### 1. Create Text Metafields

Navigate to **Settings > Custom data > Products** and add the following:

* **Badge 1**: Name it "Badge 1", Namespace and key: `custom.badge_1`, Type: **Single line text**.
* **Badge 2**: Name it "Badge 2", Namespace and key: `custom.badge_2`, Type: **Single line text**.
* **Badge 3**: Name it "Badge 3", Namespace and key: `custom.badge_3`, Type: **Single line text**.

#### 2. Create Icon Metafields (Optional)

If you wish to add unique icons to these badges, create these additional metafields:

* **Badge 1 Icon**: Namespace and key: `custom.badge_icon_1`, Type: **File (Images only)**.
* **Badge 2 Icon**: Namespace and key: `custom.badge_icon_2`, Type: **File (Images only)**.
* **Badge 3 Icon**: Namespace and key: `custom.badge_icon_3`, Type: **File (Images only)**.

> **Tip:** Once created, go to your **Product** pages in the Shopify Admin to fill in these fields with the specific text (e.g., "Limited Edition") or icons you want to display.

### Step-by-Step Setup

1. Open the **Shopify Theme Editor**.
2. Navigate to **Theme settings** (gear icon) and locate the **Badges** section.
3. Toggle **Hide badge** to `false` to ensure visibility.
4. Select a **Badge icon** (Tag, Splash, or None) to appear next to your text.
5. Customize the **Sale message**. Use `[%]` as a variable to display the actual discount percentage calculated from your product prices.
6. Adjust the **Badge size** and **Badge spacing** to ensure legibility.
7. Choose a **Badge text style** (Body, Subtitle, or Uppercase) and toggle **Bold text** if desired.
8. Set the **Position** to define which corner the badges will anchor to.
9. Assign **Color schemes** for Sale, Sold Out, and your three Custom badges to differentiate them visually.
10. Fine-tune the **Border** and **Shadow** settings to add depth.
11. Click **Save**.

### Settings Reference

| Setting                         | Type             | Default       | Description                                                 | Effect                                 |
| ------------------------------- | ---------------- | ------------- | ----------------------------------------------------------- | -------------------------------------- |
| **Hide badge**                  | checkbox         | `false`       | Completely removes badges from the storefront.              | Disables all badge rendering.          |
| **Badge icon**                  | select           | `splash`      | Choose a decorative icon to accompany badge text.           | Adds a tag or star icon.               |
| **Sale message**                | inline\_richtext | `Save [%]`    | The text shown on sale items. Use `[%]` for the percentage. | Sets the text for discounted products. |
| **Badge size**                  | range            | `11`          | Adjusts the font size of the badge text.                    | Scales the badge overall.              |
| **Badge text style**            | select           | `body`        | Choose between Body, Subtitle, or Uppercase styles.         | Changes typography appearance.         |
| **Bold text**                   | checkbox         | `false`       | Applies a heavier font weight to the badge text.            | Increases visual weight.               |
| **Badge spacing**               | range            | `0.5`         | Adjusts the gap between the badge and the image edge.       | Moves badge position slightly.         |
| **Position**                    | select           | `bottom left` | Corner placement for all badges.                            | Moves badges to Top/Bottom Left/Right. |
| **Sale badge color scheme**     | color\_scheme    | `scheme-5`    | Colors for the sale indicator.                              | Changes Sale badge background/text.    |
| **Sold out badge color scheme** | color\_scheme    | `scheme-3`    | Colors for out-of-stock products.                           | Changes Sold Out background/text.      |
| **Hide custom badges**          | checkbox         | `false`       | Hides badges generated by metafields.                       | Toggles custom metadata badges.        |
| **Custom badge 1 color scheme** | color\_scheme    | `scheme-5`    | Color for `custom.badge_1`.                                 | Styles the first custom badge.         |
| **Custom badge 2 color scheme** | color\_scheme    | `scheme-5`    | Color for `custom.badge_2`.                                 | Styles the second custom badge.        |
| **Custom badge 3 color scheme** | color\_scheme    | `scheme-5`    | Color for `custom.badge_3`.                                 | Styles the third custom badge.         |
| **Thickness**                   | range            | `1px`         | The width of the badge border.                              | Adds a solid line around the badge.    |
| **Opacity**                     | range            | `10%`         | Transparency of the border.                                 | Fades the border in/out.               |
| **Corner radius**               | range            | `0px`         | Rounds the corners of the badge.                            | Makes badges square or pill-shaped.    |
| **Shadow Opacity**              | range            | `0%`          | Strength of the badge shadow.                               | Adds depth behind the badge.           |
| **Horizontal offset**           | range            | `0px`         | Left/Right shift of the shadow.                             | Changes light source direction.        |
| **Vertical offset**             | range            | `0px`         | Up/Down shift of the shadow.                                | Changes light source height.           |
| **Blur**                        | range            | `0px`         | Softness of the shadow edges.                               | Creates a diffused shadow effect.      |

### Troubleshooting

> **Issue:** The sale percentage is not appearing. **Cause:** The `[%]` placeholder is missing from the **Sale message** setting or the product has no "Compare at price". **Solution:** Ensure **Sale message** contains `[%]` and that your product listing has a "Compare at price" higher than the current price.

> **Issue:** Custom badges are not showing up. **Cause:** Metafield keys do not match the required format or **Hide custom badges** is checked. **Solution:** Verify your metafields use the exact namespace `custom.badge_1`. Check that **Hide custom badges** is disabled in the Theme Editor.

> **Issue:** Badges are overlapping important product details. **Cause:** The **Position** is set to a corner where critical product info resides. **Solution:** Change the **Position** setting to a different corner (e.g., from `bottom left` to `top right`).

> **Issue:** Custom icons are not displaying. **Cause:** The icon metafield type is incorrect. **Solution:** Ensure `custom.badge_icon_1` is set to the **File** type and specifically limited to images.

### FAQ

#### Q: Can I show multiple custom badges on one product?

Yes. If you have values in `custom.badge_1`, `badge_2`, and `badge_3`, all three will appear stacked or aligned based on the theme's layout.

#### Q: How do I make the badges look like pills?

Set the **Corner radius** to a high value (e.g., `20px` or higher) under the Border settings.

#### Q: Does the sale percentage round up or down?

The `[%]` variable automatically calculates the percentage based on the price difference and rounds to the nearest whole number.

#### Q: Can I use different icons for Sale and Sold Out badges?

The **Badge icon** setting applies globally to standard badges. For unique icons per product, use the custom icon metafields.

#### Q: Why is my shadow not appearing?

Ensure the **Shadow Opacity** is set above `0%`. If the blur and offsets are all at `0px`, the shadow will be hidden directly behind the badge.

#### Q: Can I change the color of the Tag/Splash icon?

The icon color is determined by the text color within the selected **Color scheme** for that specific badge.