Cart experience

The cart is the most consequential UI in any e-commerce theme — it’s the final step before checkout. Hyprism gives you a cart drawer for quick reviews and a cart page for full edits, with shared block architecture so customization stays consistent.

12.1 Cart drawer vs cart page

Surface	When it shows	Best for
Cart drawer	Click cart icon → slides in from the side	Quick “what’s in my cart” check + go-to-checkout flow
Cart page (/cart)	Direct navigation to /cart or “View cart” link in drawer	Full review, edit quantities, apply discount codes, see shipping estimates

Both share the same block types — the drawer is a compact subset, the page is the full experience.

12.2 Cart Drawer

Theme settings → Cart drawer.

Behavior:

Setting	What it does
🔧 Enable cart drawer (enable_cart_drawer)	✅ Default on. When off, the header cart icon links straight to the cart page (/cart) and the slide-out drawer is not rendered. Adding to cart from a product page then updates the header count via AJAX (no page reload, no navigation) so the customer keeps shopping; only an explicit click on the cart icon goes to /cart.
🔧 Auto-open on add (cart_drawer_open_on_add)	When on, the drawer opens automatically every time the visitor adds something to cart (via Quick View, Hotspot quick-add, etc.). ✅ Default on. Standard e-commerce UX confirmation.

The drawer is hard-locked to the right side of the screen (no left-position option).

Layout:

Setting	What it does
🔧 Drawer width (cart_drawer_width)	320–560 px. ✅ Default 420. Mobile auto-collapses to 100 vw.
🔧 Drawer corner radius (cart_drawer_radius)	0–24 px. ✅ Default 0. Rounds the inside corners of the drawer card.

Color scheme:

Setting	What it does
🔧 Use global scheme (cart_drawer_use_global_scheme)	When on (default), uses the theme-wide global color scheme. When off, the 3 scheme pickers below apply.
🔧 Drawer scheme (cart_drawer_color_scheme)	Single-mode scheme override (when dark/light pair is off).
🔧 Drawer scheme (dark) (cart_drawer_color_scheme_dark)	Pair-mode dark scheme.
🔧 Drawer scheme (light) (cart_drawer_color_scheme_light)	Pair-mode light scheme.

Surface:

Setting	What it does
🔧 Transparent background (cart_drawer_transparent_bg)	Drops the solid drawer bg — useful when paired with glass for a fully translucent drawer. ✅ Default off.
🔧 Glassmorphism (cart_drawer_enable_glass)	Adds backdrop-blur to the drawer surface. ✅ Default on.
🔧 Tint glass with accent (cart_drawer_glass_tint)	When glass is on, tints with the scheme’s accent color. ✅ Default off.
🔧 Drawer effect (cart_drawer_effect)	none / shadow (hard drop-shadow under the drawer edge) / glow (accent-colored glow). ✅ Default shadow.
🔧 Glow intensity (cart_drawer_glow_intensity)	10–100. ✅ Default 50. Visible only when effect = glow.

Backdrop (the dimmed area behind the drawer):

Setting	What it does
🔧 Overlay opacity (cart_drawer_overlay_opacity)	0–100 %. ✅ Default 50. How dimmed the page is behind the drawer.
🔧 Overlay blur (cart_drawer_overlay_blur)	0–20 px. ✅ Default 4. Backdrop-blur on the page behind the drawer.

Express checkout in drawer:

Setting	What it does
🔧 Show dynamic checkout (cart_drawer_show_dynamic_checkout)	Display Shop Pay / Apple Pay / Google Pay / PayPal buttons inside the drawer. ✅ Default on.

The drawer is rendered by snippets/cart-drawer.liquid and mounted globally in layout/theme.liquid. Available on every page, hidden by default, shown when the cart icon is clicked or when the ne:cart-updated event fires.

Drawer content

• Header — “Cart (N)” + close button
• Cart Promo (optional) — free-shipping progress bar with savings message
• Cart Items — list of line-items with image, title, variant, quantity, line-total, remove button
• Cart Summary — subtotal, shipping note, checkout button, “View cart” link

12.3 Cart Promo bar (cart-promo block)

A motivational bar at the top of the cart showing progress toward a free-shipping threshold (“Add €X more for free shipping”). It’s a block that lives inside the cart section / cart-drawer — drag it into the cart-promo slot in the customizer.

Settings

Setting	What it does
🔧 Free-shipping threshold (free_shipping_threshold)	The order subtotal in your shop’s currency that unlocks free shipping (e.g., 50 for €50). ✅ Default 50. Set to 0 to hide the bar entirely. Used as the fallback when no regional metafield value matches (see below).
🔧 Regional thresholds metafield (free_shipping_threshold_metafield)	Optional. The namespace.key of a shop metafield (JSON) holding per-country / per-currency thresholds — for shops whose free-shipping limit differs by region (e.g. several euro-zone countries with different shipping rates). ✅ Default custom.free_shipping_thresholds. Leave the metafield uncreated for a single fixed threshold.
🔧 Message below threshold (message_below)	Shown while the subtotal is under the threshold. Supports the [remaining] placeholder which is replaced live with the remaining amount. ✅ Default “Add [remaining] more for free shipping”.
🔧 Message reached (message_reached)	Shown once the threshold is reached. ✅ Default “Free shipping unlocked!”.
🔧 Icon (icon)	Image upload — typically an SVG of a shipping icon. Renders left of the message. (Note: this is a free image picker, not a library-icon select — upload whatever pictogram fits your brand.)
🔧 Recolor icon (recolor_icon)	Mask-paint single-color icons with the active text color so they follow scheme + dark/light. ✅ Default off.
🔧 Icon color (icon_color)	accent / text / fg-muted — which scheme role drives the icon color. ✅ Default accent.
🔧 Surface (surface)	solid (scheme bg) / transparent (no card) / glass (blur + tint). ✅ Default glass.
🔧 Show progress bar (show_progress_bar)	Render a horizontal progress bar below the message; fills from 0 → 100 % as the subtotal approaches the threshold. ✅ Default on.
🔧 Glow (glow)	Adds the accent-colored glow around the promo card. ✅ Default off.
🔧 Shadow (shadow)	Adds a drop shadow under the promo card. ✅ Default off.
🔧 Use custom color scheme (use_custom_scheme)	Per-block scheme override (independent of the parent cart section’s scheme). ✅ Default off.
🔧 Card color scheme (card_color_scheme)	When Use custom = on, pick a scheme. ✅ Default scheme-1.

The promo updates live as cart contents change (AJAX cart update — see 12.6). The progress bar animates smoothly between values via CSS transition: width.

Regional thresholds (multi-market shops)

A single number is wrong when your free-shipping limit varies by market. To vary it:

1. Shopify Admin → Settings → Custom data → Metafields → Shop → Add definition. Namespace and key custom.free_shipping_thresholds, type JSON.

2. Set the value, keyed by country and/or currency, e.g.:

   {
     "by_country":  { "DE": 50, "AT": 60, "FR": 45 },
     "by_currency": { "EUR": 50, "USD": 75 },
     "default": 50
   }

3. The theme picks the threshold in this order: selected country → cart currency → default → the number setting above. All amounts are in the cart’s presentment currency, so a DE and AT threshold are both compared against the EUR cart total.

You maintain the JSON in the Admin metafield editor — no theme code is touched, and single-region shops can ignore this entirely (the number setting is the fallback).

12.4 Cart Items (cart-items block)

The line-items grid — each row is one product variant in the cart.

Card surface settings

Setting	What it does
🔧 Card surface (card_surface)	solid (scheme bg) / transparent / glass. ✅ Default solid. Applied to each line-item row.
🔧 Tint glass with accent (card_glass_tint)	Tints the glass rows with the scheme accent (strength = Effects → Glass tint intensity). ✅ Default off. Only visible when Card surface = glass.
🔧 Card radius (card_radius)	0–24 px. ✅ Default 8. Rounded corners on each row.
🔧 Card padding (card_padding)	0–32 px. ✅ Default 16. Inner padding.
🔧 Card glow (card_glow)	Accent glow around each row. ✅ Default off.
🔧 Card shadow (card_shadow)	Drop shadow under each row. ✅ Default off.
🔧 Gap between items (gap_between_items)	0–24 px. ✅ Default 8. Vertical gap between rows.

Content settings

Setting	What it does
🔧 Show column headers (show_column_headers)	Show a “Product / Quantity / Total” header row above the items (cart-page only — drawer always hides them for compactness). ✅ Default off.
🔧 Show product image (show_image)	Image column on each row. ✅ Default on.
🔧 Image size (image_size)	60–120 px. ✅ Default 80.
🔧 Image corner radius (image_radius)	0–40 px. ✅ Default 8. Rounded corners on the product thumbnail. Only visible when Show product image = on.
🔧 Show variant title (show_variant_title)	Display variant info under product name (“Color: Red / Size: M”). ✅ Default on.
🔧 Show unit price (show_unit_price)	When the product has Shopify unit pricing, show “€2.50 / 100 g” under the line price. ✅ Default off.
🔧 Show line discounts (show_line_discounts)	”(-€5.00)” with the discount-code or automatic-discount name when applicable. ✅ Default on.
🔧 Show remove button (show_remove_button)	Render the per-row remove button. ✅ Default on.
🔧 Quantity selector style (quantity_style)	spinner (+/- buttons around a number input) / input (number input only) / dropdown (1–10 native dropdown). ✅ Default spinner.
🔧 Remove button style (remove_style)	icon (trash icon only) / text (“Remove” link) / icon_text (icon + label). ✅ Default icon.

Color scheme override (per-block)

Setting	What it does
🔧 Use custom color scheme (use_custom_scheme)	Per-block scheme override (independent of the parent cart section’s scheme). ✅ Default off.
🔧 Card color scheme (card_color_scheme)	When Use custom = on, pick a scheme. ✅ Default scheme-1.

AJAX behavior

Each quantity change triggers /cart/change.js via AJAX:

• Optimistic UI (line hides immediately on remove)
• Promise queue (rapid-fire clicks are processed sequentially — no race conditions)
• Section re-fetch (when all mutations complete, fetch fresh section HTML to update totals + promo bar)
• Reload on empty (when cart becomes empty, reload page to show empty-state branch)

See Rule 238 in CLAUDE.md for the engineering detail.

12.5 Cart Summary (cart-summary block)

The totals + checkout button + supplementary content. Subtotal is always shown — no toggle.

Card surface + position

Setting	What it does
🔧 Surface (surface)	solid / transparent / glass. ✅ Default glass.
🔧 Position (position)	sticky (summary card sticks at the top of the info column as user scrolls) / inline (sits in normal flow). ✅ Default sticky.
🔧 Mobile sticky position (mobile_sticky_position)	none (inline on mobile) / bottom (mobile-only sticky-bottom-bar with compact subtotal + checkout). ✅ Default none.
🔧 Mobile sticky full width (mobile_sticky_full_width)	When sticky bottom-bar is on, make it edge-to-edge instead of section-aligned. ✅ Default off.
🔧 Radius (radius)	0–24 px, step 2. ✅ Default 12. Card corner radius.
🔧 Padding (padding)	8–32 px, step 2. ✅ Default 24. Inner padding.
🔧 Glow (glow)	Accent glow around the card. ✅ Default off.
🔧 Shadow (shadow)	Drop shadow under the card. ✅ Default off.

Content

Setting	What it does
🔧 Show note (show_note)	Allow the visitor to add a note to the order (gift-wrap requests, special instructions). ✅ Default on.
🔧 Note placeholder (note_placeholder)	Placeholder text inside the empty note field. ✅ Default “Add a note to your order…”.
🔧 Show dynamic checkout (show_dynamic_checkout)	Display Shop Pay / Apple Pay / Google Pay / PayPal buttons above the standard checkout button (or as fallback “Express checkout” link on dev-stores without wallet integrations). ✅ Default on.
🔧 Show taxes & shipping notice (show_taxes_shipping_notice)	“Taxes and shipping calculated at checkout” line below the subtotal. ✅ Default on.
🔧 Show estimated total (show_estimated_total)	Show the estimated total including auto-applied automatic discounts. ✅ Default off.
🔧 Show continue shopping link (show_continue_shopping_link)	Render a “Continue shopping” link below the checkout button. ✅ Default off.
🔧 Continue shopping URL (continue_shopping_url)	Where the link goes. Leave blank to default to /collections/all.

Color scheme override (per-block)

Setting	What it does
🔧 Use custom color scheme (use_custom_scheme)	Per-block scheme override. ✅ Default off.
🔧 Card color scheme (card_color_scheme)	When Use custom = on, pick a scheme.

12.6 AJAX cart updates

Hyprism’s cart updates without page reloads (the modern e-commerce UX). The pattern:

1. Visitor clicks ”+” on a line-item.
2. JS calls /cart/change.js with the line-key + new quantity.
3. Line is optimistically updated in the UI.
4. JS dispatches a custom event ne:cart-updated on document.
5. All cart listeners (drawer, summary, promo bar) listen for the event and refresh themselves.
6. Cart icon’s item-count badge updates.

This pattern means even on the cart page (with the full summary), nothing reloads. Visitor adjusts quantities, sees totals update live.

Mobile sticky cart bar

On mobile, the cart summary becomes a sticky bottom bar while the cart page is scrolled:

• Body-mounted overlay (escapes any parent containing-block — see Rule 146)
• Shows subtotal + checkout button + optional express checkout
• IntersectionObserver watches the inline summary; when it scrolls out of view, sticky bar appears

This brings the checkout CTA close at all times on mobile, where the visitor can’t see the desktop summary sidebar.

12.7 Empty cart (cart section settings)

When the cart has zero items, sections/cart.liquid shows an empty-state branch. The relevant settings live on the cart section itself (not on a block):

Setting	What it does
🔧 Empty message (empty_message)	The empty-state headline. ✅ Default “Your cart is empty”.
🔧 Empty CTA label (empty_cta_label)	Button text. ✅ Default “Continue shopping”.
🔧 Empty CTA URL (empty_cta_url)	Where the button links. Leave blank to default to /collections/all.
🔧 Empty image (empty_image)	Optional decorative image (cart icon, “empty” illustration).

The empty-state is a static layout — there is no built-in “show recently viewed on empty cart” feature. To get a browse-fallback on empty cart, drop a Recently Viewed or Featured Collection section into the Cart template (templates/cart.json) below the cart section. They’ll always be there but feel relevant when the cart is empty.

12.8 Express Checkout

Express checkout = Shop Pay, Apple Pay, Google Pay, PayPal — the “one-click” buttons that bypass the standard checkout form.

Setup

Express checkout buttons appear automatically when:

1. Shopify Payments is enabled (Shopify Admin → Settings → Payments)
2. The relevant payment methods are turned on
3. The visitor’s browser/device supports the payment method (Apple Pay on Safari/iOS, Google Pay on Chrome/Android, PayPal on any browser, Shop Pay anywhere)

Where they appear

Location	Setting
Product page	product-buy-buttons block → Show express checkout
Quick View modal	Theme settings → Quick view → Show dynamic checkout
Cart Drawer	Theme settings → Cart drawer → Show express checkout
Cart Page (summary)	Cart Summary → Show express checkout

Styling

⚠️ Express buttons are branded — Shop Pay is always purple, Apple Pay is always black, Google Pay is always white-on-black-and-blue. Hyprism doesn’t override these brand-guidelines (Shopify and the payment providers reject themes that try). What you can customize:

• border-radius — bring the buttons in line with your theme’s button shape
• width — typically full-width-of-form
• spacing / margin around the buttons

Dev-store quirk

⚠️ Shopify development stores use a Bogus Gateway for testing — it doesn’t have express-payment integrations. You’ll see the standard “Buy now” button but not Shop Pay / Apple Pay / Google Pay buttons. On a real production store with real Shopify Payments, all wallets render.

12.9 Cart drawer auto-open

When the visitor adds something to cart (from a quick-add button, Quick View, or product page), Hyprism auto-opens the cart drawer to confirm the action. This is a UX gold-standard pattern — the visitor sees their cart has been updated.

Setting	What it does
🔧 Auto-open on add (cart_drawer_open_on_add)	On / off. ✅ Default on. Located in Theme settings → Cart drawer → Behavior.

The drawer opens immediately on the ne:cart-updated event — there are no delay or auto-close settings (the visitor closes manually via the X button, backdrop click, or Escape key).

✅ The auto-open pattern works well as-is: visitor confirms the add, can immediately review the line they just added, then continue browsing or hit checkout.

Next

Chapter 13 — SEO and GEO (AI search optimization) — the structured-data and AI-discovery layer.