WooCommerce Product Labels Plugin — Badge Configuration
Overview
The Product Labels for WooCommerce plugin (EcoWebs) allows custom badges to be applied to product thumbnails in WooCommerce shop pages. Configuration is non-obvious in several areas, and client self-editing frequently breaks badge setups. This article documents key configuration patterns, known failure modes, and workarounds discovered during the [1] project.
Core Concepts
Badge Types
The plugin supports two badge tiers:
- Standard badges — simple CSS-based labels (e.g., "Sale")
- Advanced badges — custom-styled badges with shape, color, and position control; these are what enable branded labels like "Open Box"
Product Lists
Badges are not applied directly to products. Instead, you create a Product List that defines which products receive a badge, then assign a badge to that list.
Product lists can be scoped by:
- Category — any product in a given WooCommerce category
- Tag
- Manual product selection — type product names to add individually
Gotcha: The category search field in the Product List UI does not auto-populate. You must start typing the category name before results appear.
Sale Badge Behavior
The "Sale" badge is triggered automatically by WooCommerce's on-sale flag (i.e., when a product has a reduced price set). It does not require a Product List. This means it will appear on any discounted product regardless of other badge configuration.
Badge Stacking and Z-Index
The Problem
When two badges are assigned to the same position (e.g., both top-left), they overlap. The plugin's UI exposes a Z-Index field per badge, but this does not reliably control stacking order when the two badges are of different types (e.g., one standard, one advanced).
Root cause: Each badge type renders in its own absolutely-positioned container. CSS z-index only controls stacking within the same stacking context. Badges in separate containers are unaffected by each other's z-index values.
Confirmed Workaround
Give each badge a distinct position:
- Place the "Sale" badge at top-left
- Place the "Open Box" badge at top-right
This avoids the overlap entirely and communicates both statuses clearly. The client (Flynn) confirmed this was acceptable.
Attempted Z-Index Fix (Partially Works for Same-Type Badges)
If both badges are the same type, z-index can work:
- Open the badge settings for the badge you want on top
- Set its Z-Index to a higher value (e.g.,
10) - Set the competing badge's Z-Index to a lower value (e.g.,
5)
Note: the Sale badge had a default Z-Index of 99 — this must be lowered explicitly if you want another badge to appear above it.
Category-Based Badge Application
To apply a badge to all products in a WooCommerce category (e.g., "Open Box"):
- Go to Badges → Product Lists → Add New List
- Name the list (e.g., "Open Box")
- Set Taxonomy to
Category - In the Select Type field, start typing the category name — results will appear
- Select the category and save
- Assign this Product List to the desired badge in the badge's Product Selection settings
Lazy Loading / Caching Conflict
Symptom
Badges do not appear when a user first loads a filtered shop page (e.g., clicking the "Open Box" category filter). They only appear after a manual browser refresh.
Root Cause
Badges are injected into the DOM via JavaScript after the initial page load. When [2] serves a cached page, the badge injection script may run late or not at all on the first render. This is compounded by WooCommerce's AJAX-based product filtering, which re-renders the product grid without triggering a full page load.
Diagnosis Method
Fetch the raw page HTML (e.g., via curl or browser dev tools → View Source). If badge markup is absent from the initial HTML, the badges are being injected client-side and are subject to this race condition.
Resolution (In Progress)
A custom Must Use (MU) plugin is being developed to address this. The approach uses a MutationObserver to detect when the product grid is re-rendered by AJAX filtering and re-trigger badge injection at that point.
Status as of 2026-04-05: MU plugin in development. See [1] action items.
Interim Mitigation
- Clear WP Rocket cache after any badge configuration change
- Clear both the WP Rocket cache and the CDN/browser cache layers when testing
Plugin Settings Reference
Key settings under Badges → Settings → General:
| Setting | Purpose |
|---|---|
| Disable Default Badge | Suppresses WooCommerce's built-in "Sale" / "Out of Stock" labels. Enable this when using custom badges to avoid duplication. |
| Use WooCommerce Shop Hook | Default rendering method; appends badges to product thumbnails |
| Enable Product Loop Hook | Fallback if badges aren't displaying; some themes override the default hook. Warning: enabling this when badges are already showing can cause duplicates. |
| Enable Product Title Hook | Secondary fallback; generally not needed |
Client Self-Editing Risk
A recurring issue on the Flynn account is the client modifying badge settings directly in WordPress. Because the plugin's configuration is stateful (badges, product lists, and hook settings interact), a single inadvertent change can break badge display entirely and leave no obvious audit trail.
Recommended approach: Communicate clearly that badge configuration changes should be submitted as requests rather than made directly. Estimated time to diagnose a client-introduced regression: 1–2 hours.
Related
- [3]
- [4]
- [5]