Skip to content

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:

PageBlock that includes it
Off-canvas cartcomponent_offcanvas_cart_ssd_unlock_bar
Cart pagepage_checkout_cart_ssd_unlock_bar
Confirm pagepage_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:

PropertyControls
--ub-fillthe filled part of the track
--ub-trackthe empty part of the track
--ub-doneunlocked markers
--ub-textthe bar's text
--ub-htrack height
--ub-radiustrack corner radius
--ub-markermarker 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:

js
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:

FieldMeaning
qualifyingAmountthe cart value compared with every threshold
milestonesthe milestones the shopper gets, ordered by threshold
nextMilestonethe next locked milestone, or null
percenthow far the track is filled
allUnlockedtrue 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 ​

RouteDoes
POST /store-api/ssd-unlock-bar/gift/{milestoneId}/choose with giftOptionIdswaps the gift for another option (Pro)
POST /store-api/ssd-unlock-bar/gift/{milestoneId}/add-backadds 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.

Your Vision. Signed, Sealed, Delivered.