Adapt the bar in a theme or a headless storefront
This guide is for agency developers. It covers the Twig blocks, the CSS custom properties, the JavaScript events and the Store API.
Override the markup
The bar is one Twig component, @Storefront/storefront/component/ssd-unlock-bar/unlock-bar.html.twig, included on three pages:
| Page | Block that includes it |
|---|---|
| Off-canvas cart | component_offcanvas_cart_ssd_unlock_bar |
| Cart page | page_checkout_cart_ssd_unlock_bar |
| Confirm page | page_checkout_confirm_ssd_unlock_bar |
Every part of the component has its own block, starting with ssd_unlock_bar: for example ssd_unlock_bar_message, ssd_unlock_bar_track, ssd_unlock_bar_milestone, ssd_unlock_bar_gift_popover and ssd_unlock_bar_gift_choice. Extend the template in your theme and override only the blocks you need.
Gift lines in the cart are labelled through child blocks of core's line-item templates: component_line_item_type_product_ssd_gift_badge, component_line_item_type_product_ssd_gift_meta and component_line_item_quantity_ssd_gift_display.
Everything around the bar is Bootstrap 5 markup (card, badge, btn btn-link, text utilities), so a theme that restyles Bootstrap restyles it too.
Restyle with CSS custom properties
The bar's own styles read custom properties on .ssd-unlock-bar. They default to the theme's Bootstrap variables (--bs-primary, --bs-success, --bs-border-color, --bs-border-radius, --bs-body-color), so most themes need no override. The main ones:
| Property | Controls |
|---|---|
--ub-fill | the filled part of the track |
--ub-track | the empty part of the track |
--ub-done | unlocked markers |
--ub-text | the bar's text |
--ub-h | track height |
--ub-radius | track corner radius |
--ub-marker | marker size |
The plugin configuration's colours and fine controls are printed as these properties in a small scoped <style> rule, so a merchant's values win over the preset. The section carries the classes ssd-unlock-bar--preset-{native|minimal|bold|steps} and ssd-unlock-bar--marker-{photo|icon|dot|number}.
React to unlocks in JavaScript
When a milestone unlocks while the shopper watches, the storefront publishes UnlockBar/milestoneUnlocked on document.$emitter. It is dispatched as a CustomEvent on document, so either form works:
document.$emitter.subscribe('UnlockBar/milestoneUnlocked', (event) => {
const { milestoneId, reward, threshold } = event.detail;
// reward: 'free_shipping' or 'gift'; threshold: a number in the sales channel's currency
});It fires once per milestone, also for shoppers with reduced motion (only the animation is skipped). Whether a milestone is new is decided on the server and stored on the cart, so the event doesn't replay on reload and nothing is stored on the shopper's device.
Read the bar from the Store API
Every cart response from the Store API carries the bar's state in extensions.unlockBarProgress:
| Field | Meaning |
|---|---|
qualifyingAmount | the cart value compared with every threshold |
milestones | the milestones the shopper gets, ordered by threshold |
nextMilestone | the next locked milestone, or null |
percent | how far the track is filled |
allUnlocked | true when every milestone is unlocked |
Each milestone has id, type (free_shipping or gift), title, description, threshold, unlocked, remaining, declined, newlyUnlocked and icon. A gift milestone also has gift (the gift in the cart, with productId, giftOptionId, productNumber, name, value and cover) and giftOptions (the options the shopper may choose from).
newlyUnlocked is true in the first cart response after the unlock and in no later one. Use it to play the unlock moment in a headless storefront.
Change the gift from the Store API
| Route | Does |
|---|---|
POST /store-api/ssd-unlock-bar/gift/{milestoneId}/choose with giftOptionId | swaps the gift for another option (Pro) |
POST /store-api/ssd-unlock-bar/gift/{milestoneId}/add-back | adds a removed gift back |
Both recalculate the cart and return it. Removing a gift works through the normal line-item delete route, which marks it as removed. A quantity change on a gift line is refused.
Gift lines in orders
A gift is a product line item at €0 with the real product, product number, tax rules and delivery information. Its payload carries ssdCpbGiftMilestoneId, ssdCpbGiftOptionId, ssdCpbGiftThreshold and ssdCpbGiftValue. Recalculating an order in the administration never adds or removes gifts.
Rule condition
The Rule Builder condition ssdCpbMilestoneUnlocked ("Unlock Bar milestone is unlocked") takes a milestone id and matches when the cart has unlocked that milestone. It needs a cart, so it never matches in scopes without one, such as a flow on an existing order.
