Use Shopping Cart Widget when buyers need a persistent cart shortcut in the storefront header, navigation, or another shared page region. The component shows a cart icon, displays a cart badge based on the configured number display mode, and opens the shopping cart page when selected.
What this component is for
Shopping Cart Widget is an Experience Builder component for storefront navigation. It gives buyers a lightweight way to reach the cart from any page without placing the full cart experience in the layout.
This component is best suited for:
- storefront headers
- top navigation areas
- shared page templates
- custom utility regions used across the shopping experience
What buyers see
When the component is configured and published:
- the cart icon appears as a clickable link
- a numeric badge is shown for the active cart
- the badge value depends on Number Display Mode
- the widget opens the configured shopping cart page
- the badge refreshes automatically after cart updates elsewhere in the storefront
Number Display Mode controls what the badge represents:
- Count: shows the number of distinct cart line items
- Sum: shows the total quantity across all cart line items
Example:
- a cart with 2 line items at quantities 5 and 2 shows
2in Count mode - the same cart shows
7in Sum mode
If you add a label, the widget shows the label together with the badge on larger screens, for example Cart (2) or Cart (7). On phone-sized screens, the label is hidden to preserve space and only the icon remains visible.
Add the component in Experience Builder
Use these steps to place the widget where buyers can always reach their cart.
- Open Experience Builder for the storefront site.
- Open the page or shared theme layout where the cart shortcut should appear.
- In the component panel, locate Shopping Cart Widget.
- Drag the component into the target region, such as the header or navigation area.
- Select the component to open its properties.
- Configure the widget label, label color, shopping cart page name, and number display mode.
- Save and publish the site.
Component properties
Use these properties to control how the widget appears and what badge value it shows.
| Property | Default | Description |
|---|---|---|
| Widget Label | Cart | Optional text shown next to the cart icon on non-phone form factors. If left blank, the component shows only the icon and numeric badge. |
| Label Color | rgb(255,255,255) | Color used for the cart icon and label text. Choose a value that stays visible against the header or navigation background. |
| Shopping Cart Page Name | Commerce_Shopping_Cart__c | Experience Cloud named page used when the buyer opens the cart. |
| Number Display Mode | Count | Determines what the number behind the cart icon represents. Count shows the number of cart lines. Sum shows the total quantity of all items in the cart. |
Configuration guidance
Use these guidelines to avoid common Experience Builder setup issues.
Widget Label
Add a short label when the storefront design allows room for both text and icon. This works well in desktop headers where buyers benefit from a more explicit cart entry point.
Leave the label blank when you want a more compact presentation. In that case, the component shows the icon and the numeric badge only.
Label Color
Set the label color to match the header or navigation theme. The same color is applied to both the icon and the label text.
Shopping Cart Page Name
Enter the Experience Cloud named page for the shopping cart. In most storefronts, the default value is correct. Only change this when the cart page has been renamed or replaced with a custom page.
If navigation does not work after publishing, verify that the named page exists and is available in the site.
Number Display Mode
Use Count when you want the badge to represent how many separate lines are currently in the cart. This is usually the best choice when the storefront treats each cart row as a distinct selection.
Use Sum when you want the badge to represent the total quantity of units in the cart. This is usually the best choice when buyers expect the header badge to reflect all ordered units, not just the number of rows.
If your storefront already shows quantity elsewhere in the header, mini-cart, or cart summary, choose the mode that avoids mixed signals for buyers.
How the component behaves in the storefront
The widget retrieves the current cart badge value from the shopper's active cart when the page loads. If no active cart is available, the displayed value is 0.
The value returned depends on Number Display Mode:
- Count returns the number of cart lines
- Sum returns the total quantity across those lines
The badge also refreshes automatically when other storefront components publish a cart refresh event after add, update, or remove actions. This keeps the header badge aligned with the current cart state without requiring a page refresh.
The component renders only after it has resolved the current badge value and cart destination.
Where this component can be used
Shopping Cart Widget is exposed for Experience Builder placement on:
- default community component regions
- Experience Builder pages
Styling notes
The component supports storefront theming through these styling hooks:
| Styling hook | Purpose |
|---|---|
| --ocds-c-shopping-cart-widget-label-color | Sets the icon and label color |
| --ocds-c-shopping-cart-widget-counter-badge-color | Sets the badge background color |
| --ocds-c-shopping-cart-widget-label-font-size | Sets the label font size |
| --ocds-c-shopping-cart-widget-label-font-family | Sets the label font family |
These hooks are mainly useful when the storefront uses custom theme styling beyond the Experience Builder property panel.
Validation checklist
Use this quick check after publishing:
- Open the storefront as a buyer.
- Confirm the widget is visible in the intended page region.
- Confirm the cart badge is displayed.
- Set Number Display Mode to
Countand verify the badge equals the number of cart lines. - Set Number Display Mode to
Sumand verify the badge equals total quantity. - Add a product to the cart and verify that the badge updates.
- Change item quantities and confirm the badge updates correctly without a page refresh.
- Select the widget and confirm that it opens the shopping cart page.
- Review the widget on mobile to confirm the icon remains visible and the label is hidden.
Troubleshooting
The widget does not navigate to the cart page
Verify that Shopping Cart Page Name matches an existing Experience Cloud named page in the site.
The badge stays at 0
Verify that the buyer has an active cart and that cart actions in the storefront complete successfully.
The badge does not update after cart changes
Verify that the storefront components responsible for add, update, or remove actions publish the cart refresh event.
The badge number is different from expected
Verify Number Display Mode in Experience Builder.
- If the mode is
Count, the badge shows cart line count, not quantity. - If the mode is
Sum, the badge shows total quantity, not line count.
Example:
- 3 cart lines with quantities 1, 4, and 6 show
3in Count mode - the same cart shows
11in Sum mode
The text is hard to read in the header
Adjust Label Color so the icon and label have enough contrast against the background.