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 product recommendations | Shows a mini upsell row above the checkout button (default 2 cards). |
| Recommendation source | How recommendations are selected — same options as the cart page's Recommendation source. |
| Fallback collection | Fallback collection when metafield handles or API recommendations are not available. |
| Number of recommendations | Number of mini recommendation cards (range 0–4, default 2). |
| Enable delivery date picker | Opt-in delivery date input in the drawer (off by default — the drawer is a tight surface). |
| Show marketing consent checkbox | Opt-in email-marketing checkbox in the drawer. |
| Enable gift wrapping option | 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. |
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. |
| Checked by default | 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 product | The product charged when a shopper ticks the gift-wrap box. Its price is shown beside the checkbox and added to the cart as a line item, so the advertised amount is the amount charged. Leave empty to offer gift wrapping free of charge. |
Showing your own fact on every cart line
The Cart line items block has a Line detail group. Fill it in and every line in the cart — on the cart page and in the drawer — shows one extra fact taken from that product's metafield.
| Setting | What it does |
|---|---|
| Metafield | Namespace and key together, e.g. custom.hardiness_zone. This is your metafield — create it in Shopify admin and fill it in per product. Blank shows nothing. |
| Label | The words in front of the value ("Hardiness zone", "Pet type", "Service area"). |
| Unit | Appended to the value — "kg", "W", "ml". Leave blank for text facts. |
| Style | How the fact is drawn on the line. |
| Icon | An optional mark in front of the label, from the full icon library. |
| Round to a whole number | For numeric facts only. A number_decimal of 210 otherwise renders "210.0". |
A product with no value for that metafield simply shows no extra line — you do not need to fill it in for everything.
This replaced four preset-named blocks. The theme used to ship cart-pet-type-indicator, cart-dietary-tag-stack, cart-spec-summary and cart-seasonal-availability-hint. Each only displayed a metafield, was locked to one key, was named for one industry, and could not actually render — they needed a cart line that the theme's block system cannot hand them, so adding one produced an empty block. They were removed; Line detail does what all four were meant to do, for any product and any metafield you choose.
Line detail shows a fact. It does not collect one. Three other per-line features take shopper input or act on the line, and they live in the same Cart line items block — each one off until you fill it in.
| Setting | What it does |
|---|---|
| Field label (under Service location) | Puts a text box on every cart line where the shopper types an address or venue — for bookings, installs, or delivery to a place. Type a label to switch it on; leave it blank and no box appears. What the shopper types saves to that line as they go; it does not block checkout if they leave it empty. The label you type is also the name saved on the order, so call it what you want to read there — "Delivery address", "Venue", "Install location". Rename it later and anything already in a shopper's cart keeps the old name until they clear the box. |
| Quick quantities (under Bulk quantities) | Buttons beside the quantity box — type 5,10,25 and a shopper buying in counts taps once instead of typing. A button greys out if you do not have that many in stock and do not allow backorders. Leave blank to hide them. |
| Show the delivery schedule (under Subscription) | On a subscription line, shows the plan the shopper chose — "Delivers every 2 weeks" — so it is visible before checkout rather than only after. |
All three appear in the cart drawer as well as the cart page.
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)- Line detail on
cart-line-items, pointed at your own service-area metafield (per-line) - Service location on
cart-line-items— a per-line box where each shopper types the address or venue for their booking purchase-reassurance,policy-acknowledgement,cart-summary- Free-shipping bar OFF (services do not ship)
- Gift wrapping OFF
Gaoth (Pets)
cart-line-items- Line detail on
cart-line-items, pointed at your own pet-type metafield (per-line) 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-items- Line detail on
cart-line-items, pointed at your own season metafield (per-line) 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)- Line detail on
cart-line-items, pointed at your own spec metafield (per-line) purchase-reassurance,policy-acknowledgement,cart-summary- Free-shipping threshold 200
Neart (Wellness)
cart-line-itemscart-subscription-cadence-preview(per-line — same as Gaoth)- Line detail on
cart-line-items, pointed at your own dietary-tag metafield (per-line) 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 | Marks the field with an asterisk and sets the HTML required attribute. It does not block checkout — the cart form is novalidate, so treat this as a prompt rather than a gate. |
| 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
The theme does not include a discount-code entry field. Shopify's own checkout collects codes, and automatic discounts and codes applied by Shopify (for example from a link like /discount/SUMMER) are displayed in the cart and drawer as a chip plus a reduced subtotal.
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
Checkout flow
- [ ] Test applied-discount display — open
/discount/YOURCODE, then the cart: the chip and the reduced subtotal appear - [ ] 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