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. The Cart type setting (Theme settings > Cart) decides which one shoppers see. With Cart drawer (the default), the cart icon opens the drawer and the cart page stays reachable at the /cart URL. With Page, the cart icon navigates straight to /cart and the drawer never renders.
What it looks like
Here's the cart drawer alongside its 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 | Sets the slide-out cart's background and text colors. Separate from the cart page's colour set. |
| Show free shipping progress bar | Displays the free-shipping progress bar in the drawer. |
| Free shipping threshold | Order value at which the drawer's bar reads complete (range 0–500, default 75). The drawer's own value — set it to match the cart page. |
| Show discount code | Shows the discount-code field in the drawer footer. |
| Show product recommendations in drawer | Shows a mini upsell row above the checkout button (default 2 cards). |
| Drawer recommendation source | How recommendations are selected — same options as the cart page's Recommendation source. |
| Drawer fallback collection | Fallback collection when metafield handles or API recommendations are not available. |
| Number of mini cards in drawer | Number of mini recommendation cards (range 0–4, default 2). |
| Show delivery date picker in drawer | Opt-in delivery date input in the drawer (off by default — the drawer is a tight surface). |
| Show marketing consent in drawer | Opt-in email-marketing checkbox in the drawer. |
| Show gift wrapping in drawer | Opt-in gift-wrap toggle in the drawer footer. |
Every drawer setting is the drawer's own copy — nothing is shared with the cart page section, so paired values like the free-shipping threshold can diverge if you set them differently. The drawer also carries its own Empty cart group (Heading, Text, Button label, Button link, Highlight metafield). There is no order-note field in the drawer — order notes live on the cart page.
Cart page settings
In the theme editor under Sections > Cart, the settings list starts with Color scheme, followed by an Empty cart heading and, further down, a Cart upsell heading. The tables below group the settings by what they do.
General
| Setting | What it does |
|---|---|
| Color scheme | Colour set for the cart page. The drawer's colour set is its own Color scheme setting on the Cart drawer section. |
| Show discount code | Shows a discount-code input on the cart page. Uses Shopify's native /discount/{code} endpoint with a server-side redirect to /cart. Works without JavaScript. The drawer's discount field has its own Show discount code toggle. |
Empty cart
| Setting | What it does |
|---|---|
| Heading | Title shown when the cart is empty. Hidden when blank. |
| Text | Message shown in the empty-cart state. Falls back to the translated default when blank. |
| Button label | Label for the continue-shopping button. Falls back to the translated default when blank. |
| Button link | Where the continue-shopping button goes. Defaults to the all-products collection. |
| Highlight metafield | Optional product metafield reference (namespace.key). When set, each cart line on the cart page shows that metafield's value as a small capsule. Blank turns it off. The drawer has its own Highlight metafield setting — set both if you want the capsule on both surfaces. |
Free shipping
| Setting | What it does |
|---|---|
| Show free shipping progress bar | Displays a progress bar showing how close the visitor is to qualifying for free shipping. Default ON (the Uisce preset turns it off — services do not ship). |
| Free shipping threshold | Order value at which the bar reads complete (range 0–500, default 75), set in your shop's base currency. Preset demo values: Gaoth 50, Talamh 100, Tine 200, Neart 75; Uisce hides the bar instead. |
Upsell
| Setting | What it does |
|---|---|
| Show product recommendations | Shows product recommendations on the cart. Default ON. |
Recommendation 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). |
| Fallback collection | Fallback collection when metafield + API yield nothing. Required for empty-cart cross-sell. |
| Number of recommendations | 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. |
| Earliest delivery date (days from today) | Earliest selectable date — number of days from today (range 0–90, default 0). |
| Latest delivery date (days from today) | Latest selectable date — number of days from today (range 5–365, step 5, default 30). |
| Blackout dates | Dates shoppers can't pick, e.g., bank holidays. Separate with commas or new lines: single dates (2026-12-25) or ranges (2026-12-20..2026-12-26), format YYYY-MM-DD. |
| Require delivery date before checkout | Forces the shopper to pick a date before proceeding to checkout. |
| Show marketing consent checkbox | Shows an email-marketing opt-in checkbox. Posts attributes[email_consent]='true' when checked; when unchecked, no attribute is sent. Default OFF. |
| Marketing consent label | Custom label for the checkbox. Falls back to the translated default when empty. |
| Default checked | Whether the box is pre-checked. Theme Store convention: default OFF. |
| Show SMS consent checkbox | Shows an SMS-marketing opt-in checkbox. Posts attributes[sms_consent]='true' when checked; nothing when unchecked. Default OFF. |
| Order note maximum 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 option | Adds a gift-wrap toggle to the cart page. Posts as attributes[gift_wrapping]. |
| Gift wrap fee | Visual indicator only (range 0–50, default 0). It adds no charge of its own — apply the actual fee with a Shopify discount or surcharge app. |
Per-preset block composition
Each preset ships a niche-shaped cart by default — its own composition of the Cart template on that preset's store. You can add or remove blocks in the theme editor under Templates > Cart.
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 50
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 eight settings:
| Setting | What it does |
|---|---|
| Scope | Where the attribute applies. Cart posts to attributes[{key}] on the order. Line item posts to properties[{key}] on a single line, and the block has to sit in the per-line slot. Default Cart. |
| Attribute key | The underscore-cased identifier saved with the order, for example dietary_preference. Use lowercase with underscores, no spaces. |
| Visible label | The label shoppers see. Leave blank to use a generic localized label. |
| Input type | Choose Text, Dropdown, Checkbox, or Date. Default Text. |
| Required | Forces the shopper to fill it in before proceeding to checkout. |
| Options | Comma-separated values for the dropdown, for example Small, Medium, Large. Appears only when Input type is Dropdown. |
| Help text | Optional helper text shown below the input. |
| Default value | Pre-fill value (used rarely). |
Example: packaging preference (Talamh)
- Theme editor → Templates → Cart → Add block →
cart-attribute. - Set: Scope = Cart, Attribute key =
packaging_preference, Visible label =Packaging preference, Input type = Dropdown, Options =Eco-friendly, Standard, Premium, Help text =Eco-friendly uses recycled materials. - Save. Orders 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 option toggle:
- Turn off Enable gift wrapping option on the Cart section.
- Add a
cart-attributeblock: Attribute key =gift_wrap_message, Visible label =Gift message, Input type = Text. - Add a second block: Attribute key =
gift_recipient_name, Visible 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 single line text. - Save. Fill the field on each product with the handles of the recommended products, one handle per entry.
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 checks each line's availability with a GET /products/{handle}.js request, cached per variant for 60 seconds. If any item is no longer available, a banner appears above the cart summary with a heading, a short instruction, and a Try again button. The affected lines are flagged in place: each one gets a "Sold out" overlay plus its own Remove and Update quantity buttons. The Check out button stays disabled until the banner clears, which happens when Try again finds everything available or when a cart update leaves nothing out of stock. 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 Recommendation 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 footer stays on screen when the out-of-stock banner appears — the banner and the disabled Check out button do the gating.
Cart drawer vs. cart page
Pick the one your shoppers see with Cart type in Theme settings > Cart.
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. It carries the same features as the cart page, but the delivery date picker, marketing consent checkbox, and gift-wrapping toggle are opt-in there, and it has no order-note field.
The cart page works best when visitors buy 5+ items or when you want order notes and the full set of cart attributes on screen at once alongside the summary.
Before you go live
Settings
- [ ] Fallback collection is set on the Cart section and on the Cart drawer section (otherwise empty-cart cross-sell shows nothing)
- [ ] Metafield definitions are created in Shopify admin per the namespace guide above
- [ ] Blackout dates are correct for your business (if the delivery date picker is enabled)
- [ ] Per-preset niche blocks make sense for your products (remove blocks that do not apply)
- [ ] Free shipping threshold matches your actual shipping policy on both the Cart section and the Cart drawer section
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 stays visible when the out-of-stock banner is active, with Check out disabled
- [ ] 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 rejected — the date picker still offers them, but choosing one shows an error, saves nothing, and blocks checkout
- [ ] 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 in from inline-end in LTR locales — the right of the screen (English, French, Spanish, etc.)
- [ ] Cart drawer slides in from inline-end in RTL locales too — the left of the screen (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 / two / 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