Appearance
Cart
Uisce has two cart experiences: a drawer that slides in from the side when visitors add an item, and a full cart page at /cart. Both are always available — the drawer opens from the cart icon, and the cart page is accessible via the /cart URL.
What it looks like
Here's the cart drawer alongside the cart page settings.
Cart drawer preview
Empty cart
When a visitor opens the cart with nothing in it, they see a friendly message with a link to keep shopping:
Empty cart state
Cart drawer settings
The cart drawer has its own settings separate from the cart page. Because the drawer is a narrower surface, some features are opt-in only.
| Setting | What it does |
|---|---|
| Color scheme | Which colour set the drawer uses. |
| Show free shipping bar | Displays the free-shipping progress bar in the drawer. |
| Free shipping threshold | Order value at which shipping becomes free. Shared with the cart page. |
| Enable discount code | Shows the discount-code field in the drawer footer. |
| Enable upsell | Shows mini product-recommendation cards in the drawer footer (default limit: 2 cards). |
| Upsell source | How recommendations are selected — see the cart page upsell settings for options. |
| Upsell collection | Fallback collection when metafield + API yield no results. |
| Upsell limit | Number of recommendation cards (range 0–12, default 2 in the drawer). |
| Enable delivery date picker (drawer) | Opt-in delivery date input in the drawer (off by default — the drawer is a tight surface). |
| Enable marketing consent (drawer) | Opt-in email-marketing checkbox in the drawer. |
| Enable gift wrapping (drawer) | Opt-in gift-wrap toggle in the drawer. |
The drawer inherits upsell_source_tier, upsell_collection, cart_note_max_length, and free_shipping_threshold from the cart section (single source of truth for cart-level configuration).
Cart page settings
In the theme editor under Sections > Cart, you'll find settings across five groups.
General
| Setting | What it does |
|---|---|
| Color scheme | Colour set for the cart page and drawer. |
| Enable discount code | Shows a discount-code input on the cart page sidebar and drawer footer. Uses Shopify's native /discount/{code} endpoint with a server-side redirect to /cart. Works without JavaScript. |
Free shipping
| Setting | What it does |
|---|---|
| Show free shipping bar | Displays a progress bar showing how close the visitor is to qualifying for free shipping. Default ON (OFF for Uisce preset — services do not ship). |
| Free shipping threshold | Order value ($) at which shipping becomes free. Per-preset defaults: Uisce $0, Gaoth $75, Talamh $100, Tine $200, Neart $75. |
Upsell
| Setting | What it does |
|---|---|
| Enable upsell | Shows product recommendations on the cart. Default ON. |
Upsell source (upsell_source_tier) | How the theme picks recommended products: cascade (default — tries metafield → Recommendations API → collection in order), metafield_only (full curatorial control), api_only (Shopify machine-learning recommendations), collection_only (merchant-curated collection fallback). |
| Upsell collection | Fallback collection when metafield + API yield nothing. Required for empty-cart cross-sell. |
| Upsell limit | Number of cards to show (range 0–12, default 4 on the cart page). |
Cart attributes
| Setting | What it does |
|---|---|
| Enable delivery date picker | Shows a date input where shoppers pick a delivery or appointment date. Posts as attributes[delivery_date]. Default OFF; ON + required for the Uisce preset. |
| Delivery date min offset | Earliest selectable date — number of days from today (range 0–90, default 0). |
| Delivery date max offset | Latest selectable date — number of days from today (range 5–365, step 5, default 30). |
| Delivery date blackout | Dates to block (textarea — one ISO date YYYY-MM-DD per line, e.g., bank holidays). |
| Delivery date required | Forces the shopper to pick a date before proceeding to checkout. |
| Enable marketing consent | Shows an email-marketing opt-in checkbox. Posts as attributes[marketing_consent]=true/false. Default OFF. |
| Marketing consent label | Custom label for the checkbox. Falls back to the translated default when empty. |
| Marketing consent default | Whether the box is pre-checked. Theme Store convention: default OFF. |
| Enable SMS consent | Shows an SMS-marketing opt-in checkbox. Posts as attributes[sms_consent]=true/false. Default OFF. |
| Cart note max length | Character limit for the order-notes field (range 100–2000, default 500). Order notes are always shown on the cart page. |
| Enable gift wrapping | Adds a gift-wrap toggle to the cart page. Posts as attributes[gift_wrapping]. |
| Gift wrap fee | Optional gift-wrap fee (range 0–50, default 0). |
Per-preset block composition
Each preset ships a niche-shaped cart by default. You can add or remove blocks in the theme editor under Templates > Cart.[preset].
Uisce (Services)
cart-line-items(always present)cart-delivery-date-picker(cart-level — shoppers book service appointments;delivery_date_requiredis ON by default)cart-service-location(per-line text input for the address or venue of each service)purchase-reassurance,policy-acknowledgement,cart-summary- Free-shipping bar OFF (services do not ship)
- Gift wrapping OFF
Gaoth (Pets)
cart-line-itemscart-pet-type-indicator(per-line — readsproduct.metafields.uisce_gaoth.pet_type)cart-subscription-cadence-preview(per-line — readsitem.selling_plan_allocationfor food subscriptions)purchase-reassurance,policy-acknowledgement,cart-summary- Free-shipping threshold $75
Talamh (Garden)
cart-line-itemscart-seasonal-availability-hint(per-line — readsproduct.metafields.uisce_talamh.season)cart-bulk-shipping-notice(cart-level — renders when cart total weight exceeds a configurable threshold; default 5 kg)purchase-reassurance,policy-acknowledgement,cart-summary- Free-shipping threshold $100
Tine (Hardware)
cart-line-itemscart-bulk-quantity-shortcuts(per-line — quick-quantity buttons at 5 / 10 / 25; respects inventory cap)cart-spec-summary(per-line — readsproduct.metafields.uisce_tine.{wattage,size,power_source,battery_compat})purchase-reassurance,policy-acknowledgement,cart-summary- Free-shipping threshold $200
Neart (Wellness)
cart-line-itemscart-subscription-cadence-preview(per-line — same as Gaoth)cart-dietary-tag-stack(per-line — readsproduct.metafields.uisce_neart.dietary_taglist)purchase-reassurance,policy-acknowledgement,cart-summary- Free-shipping threshold $75
Cart-attribute block authoring
Beyond the built-in cart attributes (delivery date, marketing consent, gift wrapping), you can add any custom order attribute using the free-form cart-attribute block. Each block has seven settings:
| Setting | What it does |
|---|---|
| Key | The attribute key — becomes attributes[{key}] on the order. Use lowercase with underscores, no spaces. |
| Label | The visible label shoppers see. |
| Input type | Choose text, select, checkbox, or date. |
| Required | Forces the shopper to fill before proceeding to checkout. |
| Options | For select type: comma-separated list of choices. |
| Info | Optional helper text shown below the input. |
| Default value | Pre-fill value (used rarely). |
Example: packaging preference (Talamh)
- Theme editor → Templates → Cart.talamh → Add block →
cart-attribute. - Set: key =
packaging_preference, label =Packaging preference, input type =select, options =Eco-friendly,Standard,Premium, info =Eco-friendly uses recycled materials. - Save. Orders will show
packaging_preference: Eco-friendlyin the order detail.
Example: gift message with custom recipient name
To collect per-recipient details beyond the simple enable_gift_wrapping toggle:
- Disable
enable_gift_wrappingon the cart section. - Add a
cart-attributeblock: key =gift_wrap_message, label =Gift message, input type =text. - Add a second block: key =
gift_recipient_name, label =Recipient name, input type =text.
Multiple cart-attribute blocks can be stacked in any order.
Product metafields for cart blocks
Some cart blocks read product metafields. You create the metafield definitions in Shopify admin — the theme reads them but cannot install them (Shopify Theme Store policy forbids themes from auto-installing metafield definitions). Go to Shopify admin → Settings → Custom data to create definitions.
uisce_cart.cross_sells (all presets)
For per-product upsell control. Used by the first tier of the upsell cascade.
- Shopify admin → Settings → Custom data → Products → Add definition.
- Namespace:
uisce_cart, key:cross_sells. - Type:
List of product handles. - Save. Fill the field on each product with handles of recommended products.
uisce_gaoth.pet_type (Gaoth only)
- Namespace:
uisce_gaoth, key:pet_type. Type:Single line text. - Optional validation preset list:
Dog, Cat, Bird, Fish, Reptile, Small animal, Other.
uisce_talamh.season (Talamh only)
- Namespace:
uisce_talamh, key:season. Type:Single line text. - Validation preset list:
Spring, Summer, Fall, Winter, Year-round.
uisce_tine.{wattage,size,power_source,battery_compat} (Tine only)
Four separate definitions, all Single line text:
wattage(e.g.,1500W)size(e.g.,12 in)power_source(Battery,Corded,Gas)battery_compat(battery system compatibility, e.g.,M12 / M18)
uisce_neart.dietary_tag (Neart only)
- Namespace:
uisce_neart, key:dietary_tag. Type:List of single line text. - Example values:
Gluten-free,Vegan,Organic,Sugar-free.
How cart behaviors work
Quantity updates
Clicking + or − updates the displayed total and line price immediately before the network request completes. If the request fails, the displayed quantity rolls back to the server-confirmed value. Rapid-fire clicks are coalesced — intermediate states are discarded, and the latest value wins.
Inventory cap
When a product has inventory tracking enabled and is set to sell only while in stock, shoppers cannot increase quantity past the available stock. An inline "Only N available" message appears. If inventory changes during the session, the server returns the updated cap and the displayed quantity adjusts automatically.
Out-of-stock banner at checkout
Before redirecting to Shopify checkout, the theme verifies inventory via /cart.js. If any item is no longer available, a banner appears above the cart summary listing the out-of-stock items and offering Remove and Update controls. The Check out button is disabled until the issue is resolved. After three network failures, the theme falls back to native form submit (Shopify checkout handles out-of-stock at the platform level as a safety net).
Discount codes
Only one discount code applies at a time, matching Shopify's native cart-level discount semantics. Entering a new code replaces the previous one — no error, no stack. Gift cards stack natively at Shopify checkout.
Upsell cascade
When you have items in cart, the theme picks recommendations in this order: per-product metafield (uisce_cart.cross_sells) → Shopify Recommendations API (intent=complementary) → fallback collection. An empty cart goes straight to the fallback collection. You can fix the tier by changing the Upsell source setting.
Sticky mobile checkout footer
On mobile viewports (below 1024 px), a sticky footer repeats the Check out button and subtotal so shoppers do not need to scroll. iOS safe-area inset is respected via env(safe-area-inset-bottom). The sticky footer is suppressed when the out-of-stock banner is active — the shopper must resolve the issue before checking out.
Cart drawer vs. cart page
The drawer works best when visitors typically buy 1–3 items. It keeps them on the page they were browsing, so they can easily add more products.
The cart page works best when visitors buy 5+ items or when you want to show the free shipping bar, gift wrapping option, delivery date picker, or other detailed information alongside the cart.
Before you go live
Settings
- [ ]
upsell_collectionis set on every cart section (otherwise empty-cart cross-sell shows nothing) - [ ] Metafield definitions are created in Shopify admin per the namespace guide above
- [ ] Delivery date blackouts are correct for your business (if delivery date picker is enabled)
- [ ] Gift-wrap fee tax handling matches your merchant tax settings (if
gift_wrap_fee> 0) - [ ] Per-preset niche blocks make sense for your products (remove blocks that do not apply)
- [ ]
free_shipping_thresholdmatches your actual shipping policy
Discount and checkout flow
- [ ] Test discount code apply — enter code, click Apply, discount appears in summary
- [ ] Test discount code remove — click × on applied chip, discount disappears
- [ ] Test invalid code — enter garbage, error message displays
- [ ] Test single-code replace — enter code A, then code B, only B applies
- [ ] Test out-of-stock banner — drop a variant's inventory, add to cart, click Check out
Quantity and inventory
- [ ] Quantity + / − updates total immediately
- [ ] Quantity cannot exceed inventory when stock tracking is on
- [ ] Adding from an upsell card opens the drawer and adds the line
Mobile and drawer
- [ ] Cart drawer and cart page tested on iOS Safari, Chrome mobile, and Firefox
- [ ] Sticky mobile checkout footer visible below 1024 px
- [ ] Sticky footer disappears when the out-of-stock banner is active
- [ ] iOS safe-area-bottom respected (footer does not sit behind the home indicator)
Cart attributes
- [ ] Delivery date picker accepts dates within the min / max offset window
- [ ] Blackout dates are not selectable
- [ ] Marketing consent checkbox state arrives on the order confirmation
- [ ] Gift-wrap toggle posts as
attributes[gift_wrapping]=trueon the order - [ ] Custom
cart-attributeblocks post their key and value to order confirmation
Localization and RTL
- [ ] Cart drawer slides from inline-end in LTR locales (English, French, Spanish, etc.)
- [ ] Cart drawer slides from inline-start in RTL locales (Arabic, Hebrew, Persian, Urdu)
- [ ] All cart strings translate correctly across your published locales
- [ ] CLDR plural forms render correctly in cart-count aria-label (zero / one / few / many / other)
Performance and accessibility
- [ ] No axe violations on
/cart - [ ] Lighthouse Performance ≥ 0.6 desktop on the cart page
- [ ] Lighthouse Accessibility ≥ 0.9 desktop on the cart page
- [ ] No visible layout shift when the cart drawer opens or mounts
Related guides
- Cart support — diagnostics and troubleshooting
- Translations — 50 locales and RTL
- Theme settings — global logo, color schemes, and layout
- Color schemes — choosing and customizing colour sets