Free-shipping bar and upsell for the cart
A "₹250 more for free shipping" progress bar and a row of add-on products, from useCart() and the store's free-shipping threshold in store().
Goal: a block that shows how far the cart is from free shipping, as a progress bar, and offers a few add-on products the shopper can add with one click.
Where it can go. The slide-out cart drawer is the storefront host's own component, mounted
outside your theme: a theme cannot add content to it today. Put this block on the cart page
(layouts/cart.json, above or below the cart block), or anywhere else a shopper sees before
checkout. It follows the cart live, so it updates the moment an item is added from anywhere on the
page.
The island
'use client';
import { useCart, useCartActions } from '@bizzpocket/theme/client';
export type Pick = {
id: string;
handle: string;
title: string;
amount: number;
currency: string;
image: { src: string; alt: string } | null;
};
const money = (amount: number, currency: string) =>
new Intl.NumberFormat(undefined, { style: 'currency', currency, maximumFractionDigits: 0 }).format(amount);
export function CartExtras({
threshold,
currency,
picks,
upsellHeading,
reachedText,
}: {
threshold: number | null;
currency: string;
picks: Pick[];
upsellHeading: string;
reachedText: string;
}) {
const { cart, ready } = useCart();
const { add, pending, error } = useCartActions();
const lines = cart?.items ?? [];
// The subtotal the host sends; summed from the lines when a host leaves it out.
const subtotal = cart?.totals?.subtotal?.amount ?? lines.reduce((n, l) => n + (l.lineTotal?.amount ?? 0), 0);
const cur = cart?.totals?.subtotal?.currency ?? cart?.currency ?? currency;
const inCart = new Set(lines.map((l) => l.productId));
const offers = picks.filter((p) => !inCart.has(p.id)).slice(0, 3);
const left = threshold === null ? 0 : Math.max(0, threshold - subtotal);
const share = threshold === null ? 0 : Math.min(1, subtotal / threshold);
const showBar = threshold !== null && ready && lines.length > 0;
return (
<div className="cx">
{threshold !== null ? (
// The bar's box is always there (empty until the cart answers), so nothing below it moves.
<div className="cx__ship" aria-live="polite">
<p className="cx__ship-text">
{!showBar ? ' ' : left > 0 ? `Add ${money(left, cur)} more for free shipping.` : reachedText}
</p>
<div className="cx__track" aria-hidden="true">
<div className="cx__fill" style={{ transform: `scaleX(${showBar ? share : 0})` }} />
</div>
</div>
) : null}
{offers.length > 0 ? (
<div className="cx__upsell">
<h3 className="cx__heading">{upsellHeading}</h3>
<ul className="cx__list">
{offers.map((p) => (
<li key={p.id} className="cx__item">
{p.image ? <img className="cx__img" src={p.image.src} alt={p.image.alt} width={64} height={64} loading="lazy" /> : <span className="cx__img" />}
<a className="cx__title" href={`/products/${encodeURIComponent(p.handle)}`}>
{p.title}
</a>
<span className="cx__price">{money(p.amount, p.currency)}</span>
<button
type="button"
className="cx__add"
disabled={pending}
onClick={() => add({ productId: p.id, handle: p.handle, quantity: 1 }).catch(() => {})}
>
Add
</button>
</li>
))}
</ul>
{/* VARIANT_REQUIRED: the product has options; send the shopper to its page instead. */}
{error !== null ? <p className="cx__error" role="alert">{error.message}</p> : null}
</div>
) : null}
</div>
);
}The block
import { block, f, products, store } from '@bizzpocket/theme';
import { CartExtras } from './cart-extras-view';
import './cart-extras.css';
export default block({
name: 'Cart extras',
category: 'commerce',
description: 'How far the cart is from free shipping, and a few add-ons to reach it.',
// On the cart page the shopper is looking at it: interactive at once.
hydrate: 'load',
fields: {
upsellCollection: f.collection({ label: 'Add-on products from' }),
upsellHeading: f.text({ default: 'Goes well with your order' }),
reachedText: f.text({ default: 'You get free shipping.' }),
},
data: ({ upsellCollection }) => ({
shop: store(),
picks: products({ collection: upsellCollection, first: 6 }),
}),
render: ({ shop, picks, upsellHeading, reachedText }) => {
// A store with no free-shipping threshold (null or 0) gets no bar.
const threshold = shop?.freeShippingThreshold && shop.freeShippingThreshold > 0 ? shop.freeShippingThreshold : null;
const list = (picks?.products ?? []).map((p) => ({
id: p.id,
handle: p.handle,
title: p.title,
amount: p.price.amount,
currency: p.price.currency,
image: p.image ? { src: p.image.src, alt: p.image.alt } : null,
}));
if (threshold === null && list.length === 0) return null;
return (
<CartExtras
threshold={threshold}
currency={shop?.currency ?? 'INR'}
picks={list}
upsellHeading={upsellHeading}
reachedText={reachedText}
/>
);
},
});[data-theme] .cx {
display: flex;
flex-direction: column;
gap: 1.5rem;
}
[data-theme] .cx__ship-text {
margin: 0 0 0.5rem;
min-height: 1.5em;
}
[data-theme] .cx__track {
height: 0.5rem;
overflow: hidden;
border-radius: 999px;
background: var(--color-surface, rgba(0, 0, 0, 0.08));
}
/* scaleX, not width: no reflow while it moves. */
[data-theme] .cx__fill {
height: 100%;
background: var(--color-primary, #1a7f37);
transform-origin: left;
transition: transform 0.3s ease;
}
@media (prefers-reduced-motion: reduce) {
[data-theme] .cx__fill {
transition: none;
}
}
[data-theme] .cx__heading {
margin: 0 0 0.75rem;
font-size: 1rem;
}
[data-theme] .cx__list {
display: grid;
gap: 0.75rem;
margin: 0;
padding: 0;
list-style: none;
}
[data-theme] .cx__item {
display: grid;
grid-template-columns: 4rem minmax(0, 1fr) auto auto;
align-items: center;
gap: 0.75rem;
}
[data-theme] .cx__img {
width: 4rem;
height: 4rem;
object-fit: cover;
border-radius: var(--radius-card, 0.5rem);
background: var(--color-surface, rgba(0, 0, 0, 0.04));
}
[data-theme] .cx__title {
color: inherit;
}
[data-theme] .cx__add {
padding: 0.5rem 0.875rem;
border: 1px solid currentColor;
border-radius: var(--radius-button, 0.5rem);
background: transparent;
color: inherit;
font: inherit;
cursor: pointer;
}
[data-theme] .cx__error {
margin: 0;
color: var(--color-error, #b42318);
}Add it to the cart page with bizzpocket add-to-layout cart-extras --page cart.
How it works
- The threshold comes from
store()indata():freeShippingThreshold, in the store's currency and in the same units as product prices (599means ₹599).nullor0means the store has no free shipping, and the block renders no bar. Because the threshold is decided on the server, the bar is either always there or never there: it never pops in. - The cart comes from
useCart()in the browser. Until the host answers (readyisfalse) the bar is empty and the text line holds a non-breaking space, so the block keeps its height. - The maths.
left = threshold - subtotal. The subtotal is the cart'stotals.subtotal, before shipping. Discounts and the exact shipping rule are applied at checkout, which stays the authority: treat the bar as a nudge, not a quote. - The upsell. Up to six products of a collection come with the page (static data). The island hides
the ones already in the cart and shows three. "Add" calls
useCartActions().add(), which sends the same events assir.addToCart(and opens the cart drawer).useCart()then gets the new cart, so the bar moves and the added product leaves the list. - Products with options. Adding one without a variant fails with
VARIANT_REQUIRED, and the island shows the store's message. Pick a collection of simple add-ons (gift wrap, batteries, socks), or link to the product instead of adding it.
JS cost
One island, about 2 KB gzip in the client gz column (useCart, useCartActions and the view;
React is shared by every island). hydrate: 'load' wakes it with the page's scripts, since it is the
point of the cart page. CSS is about 0.5 KB gzip.
What is missing in the SDK
- No slot in the host's cart drawer: themes cannot add a free-shipping bar or an upsell to it.
- The cart events carry no shipping estimate, so the bar compares the subtotal with the threshold; it cannot know a coupon that changes the rule.
See also
- Interactivity: client hooks:
useCart(). - Interactivity: cart actions:
add(),pending,error. - Data:
store()andproducts(), and why this block isstatic.