Product sections

The product page is the conversion engine of any e-commerce store. Hyprism’s product architecture is block-first — sections/product.liquid is a thin @theme container, and the actual product UI is composed of 13 dedicated blocks that you arrange freely.

This chapter covers:

• The product page (template + section)
• 13 product blocks
• 4 related/promotional sections (Featured Product, Recently Viewed, Related Products, Wishlist)

7.1 Product page (product template + section)

The product page has two parts:

• Section-level: column structure, media aspect, surface effects, padding (settings on sections/product.liquid itself).
• Block-level: the info column is a block container — drop in the 13 product blocks you need, in any order.

Section settings — layout

Setting	What it does
🔧 Layout mode (layout_mode)	split (2-column media + info side-by-side) / unified (single column, media first then info below) / stacked (media as sticky background, info scrolls over). ✅ Default split.
🔧 Scroll behaviour (scroll_behavior)	sticky (info column sticks at top while media scrolls) / parallel (both columns scroll together). ✅ Default sticky. Affects the split layout only (no effect in unified/stacked modes).
🔧 Swap columns (swap_columns)	When split, puts media on the right instead of left. ✅ Default off.
🔧 Media column width (media_column_width)	30–70 %. ✅ Default 50. Sets the media-to-info column ratio.
🔧 Media aspect ratio (media_aspect_ratio)	natural (image native ratio) / 1-1 / 4-5 / 3-4 / 16-9. ✅ Default natural.
🔧 Gap (gap)	0–80 px. ✅ Default 40. Horizontal gap between media and info columns.
🔧 Thumbnail size (thumb_size)	40–120 px. ✅ Default 64. Size of the thumbnail strip below the main media.
🔧 Thumbnail layout (thumb_layout)	slider (horizontal scroll, default) / grid (auto-fill columns based on thumbnail size) / auto (grid on desktop ≥ 750 px, slider on mobile). ✅ Default slider. Grid column count is computed automatically from the thumbnail size — bigger thumbs ⇒ fewer columns.

Thumbnails are always shown when the product has > 1 image — there is no toggle to hide them; instead, use a single product image if you don’t want a thumb strip.

Section settings — card surface + effects

These apply to the info column’s “card” wrapper (the container around the block stack):

Setting	What it does
🔧 Card surface (card_surface)	none (no card chrome — blocks render directly) / solid (scheme bg-surface) / glass (frosted) / transparent. ✅ Default none.
🔧 Tint glass with accent (card_glass_tint)	Tints the glass card with the scheme accent color (strength = Effects → Glass tint intensity). ✅ Default off. Only visible when Card surface = glass.
🔧 Use global card radius (use_global_card_radius)	When on (default), card uses the theme-wide --ne-radius-md token. When off, the slider below applies.
🔧 Card radius (card_radius)	0–32 px, step 2. ✅ Default 12. Only visible when Use global card radius = off.
🔧 Media effects (media_effects)	none / glow / shadow / both. ✅ Default none. Applied to the media column.
🔧 Info effects (info_effects)	none / glow / shadow / both. ✅ Default none. Applied to the info column.

Section settings — lightbox

Setting	What it does
🔧 Lightbox background opacity (lightbox_bg_opacity)	0–100 %, step 5. ✅ Default 40. Opacity of the dark backdrop behind the full-screen image lightbox. The lightbox itself is always available — clicking the main image opens it with keyboard navigation (arrows, escape).

Section settings — universal v7 chrome

The Product section also carries the universal v7 chrome (same as every other v7 section):

Setting group	Covers
Color scheme	Transparent background (transparent_bg, default off — when on, the section paints no scheme bg and shows the page-level background through) / Use global / Color scheme / Dark + Light pair (see §2.2)
Section sizing	Full width / Full width mobile / Padding top / Padding bottom / Padding X / Custom mobile padding (+ mobile padding Y / X)
Image radius	Use global image radius / Image corner radius

Layout mode — sticky-stacked deep-dive

The stacked mode is a Hyprism-distinctive layout: media sits as a position: sticky background layer; the info column scrolls over it. Visually striking for lifestyle / luxury products with one iconic hero image.

Internal implementation:

• Media gets position: sticky; z-index: 0
• Info gets position: relative; z-index: 1
• Info has an opaque or glass background so it covers the media as it scrolls over

⚠️ Stacked requires a tall enough section for the scroll-over to feel intentional. Avoid on short product pages.

7.2 Product blocks (13 blocks)

These blocks are designed for product templates but most also work in custom sections (e.g., the Quick View modal, Featured Product section).

Product-vendor (product-vendor)

Displays the vendor name above the product title. Tiny eyebrow text. Only renders if product.vendor is set in Shopify Admin.

Setting	What it does
🔧 Alignment (alignment)	left / center / right. ✅ Default left.
🔧 Size (size)	xs / sm / md / lg / xl / 2xl. ✅ Default sm. Maps to font-size tokens.
🔧 Uppercase (uppercase)	Force text-transform: uppercase + slight letter-spacing for eyebrow look. ✅ Default on.

The vendor links to /collections/vendors?q={vendor} automatically — there is no toggle to disable the link.

Product-title (product-title)

The product title element. Carries both the visible heading style and the semantic HTML tag for SEO.

Setting	What it does
🔧 HTML tag (heading_tag)	h1 / h2 / h3. ✅ Default h1. For SEO, h1 is correct on product pages (one h1 per page).
🔧 Visual size (heading_size)	h1 / h2 / h3 / h4 / h5 / h6. ✅ Default h1. Independent of the semantic tag — you can render visually as h3-sized while keeping the semantic h1 tag.
🔧 Font role (font_role)	body / subheading / heading / accent. ✅ Default heading. Pulls the font family from the theme typography role.
🔧 Alignment (alignment)	left / center / right. ✅ Default left.

Product-price (product-price)

The price line, with sale-price + compare-at-price + unit-price + tax-notice support. The block automatically handles single-variant + multi-variant pricing, switching between “from {min}” and exact prices.

Setting	What it does
🔧 Size (size)	sm / md / lg / xl / 2xl / 3xl. ✅ Default lg. Maps to font-size tokens.
🔧 Alignment (alignment)	left / center / right. ✅ Default left.
🔧 Show unit price (show_unit_price)	When the product has unit pricing (e.g., “€2.50 / 100 g” for food/cosmetics), show it below the main price. ✅ Default on.
🔧 Show tax notice (show_tax_notice)	When the shop has Shopify tax settings configured, show the “Tax included / excluded” notice. ✅ Default on.

The block reads --ne-scheme-text (regular price + compare-at strike-through) and --ne-scheme-sale (sale price) from the active color scheme. The sale color comes from the Sale-Preis role in Color schemes; the regular / compare-at prices follow the Text role.

Product-variant-picker (product-variant-picker)

Lets visitors choose product variants (color, size, material, etc.). Picker style is per-option-type — color options can render differently from size options.

Setting	What it does
🔧 Color swatch style (color_swatch_style)	color (round color dots — default) / button (pill-style buttons with the color name as label) / select (compact native dropdown). ✅ Default color.
🔧 Size swatch style (size_swatch_style)	button (pill-style buttons with size value) / select (native dropdown). ✅ Default button.
🔧 Show selected value (show_selected_value)	Display the currently-selected option value next to the option name (“Color: Red”). ✅ Default on.
🔧 Alignment (alignment)	left / center / right. ✅ Default left.
🔧 Glow (variant_glow)	Adds a soft glow to the selected variant swatch/button only. ✅ Default off.
🔧 Glow source (variant_glow_source)	accent (theme accent color) / variant (the swatch’s own color, lightened for visibility). ✅ Default accent. Only visible when Glow is on.
🔧 Shadow (variant_shadow)	Adds a drop shadow to variant swatches/buttons. ✅ Default off.

A11y: each radio input gets aria-label="OptionName: Value" for screen-readers. When Effects → Glass color swatches is on, color swatches also get a glass sheen.

Setting up color swatches (any language, any custom brand color) — the theme reads values in this order, first hit wins:

1. Shopify’s native Color picker — option.values[i].swatch.color / .swatch.image. Set in Admin → Products → Options → “Edit values” when the option type is Color. Recommended for any non-English store + any brand-custom color.
2. Built-in DE + EN dictionary (~60 names): Schwarz / Black, Marineblau / Navy, Bronze, Cognac, Mauve, Türkis, Khaki, Petrol, etc. Used when no native swatch is configured.
3. handleize fallback — works for English values that coincide with CSS keywords.

To enable the native color picker:

1. Admin → Products → select product → scroll to Variants
2. Click “Edit options” on the Color option
3. Change option type from “Custom (text)” to “Color”
4. Pick a hex per value, or upload a swatch image (wood / fabric / brand pattern)
5. Save — the theme renders the picked color (or image) on cards + PDP variant picker

See also: 19.1 Variant-selector swatches show empty / wrong color.

Product-buy-buttons (product-buy-buttons)

The add-to-cart form with quantity selector + optional dynamic checkout (Shop Pay / Apple Pay / Google Pay / PayPal).

Setting	What it does
🔧 Show quantity selector (show_quantity)	Toggle the +/- spinner. ✅ Default on.
🔧 Quantity layout (qty_layout)	stacked (qty above ATC) / inline (qty + ATC on the same row). ✅ Default inline. Visible only when quantity selector is on.
🔧 Show dynamic checkout (show_dynamic_checkout)	Display Shop Pay / Apple Pay / Google Pay / PayPal buttons below the ATC button (requires Shopify Payments + relevant wallets enabled). ✅ Default on.
🔧 Show Shop Pay Installments banner (show_installments)	Shows the “Pay in installments” banner below the buttons. Renders only when the shop and product are eligible (Shop Pay Installments enabled, price within range); otherwise nothing shows. ✅ Default on.
🔧 Quantity selector full width (full_width)	When on, the quantity selector spans the full info-column width. ✅ Default off. (The ATC button width is set by Buttons width above, independently.)
🔧 Buttons width (buttons_width)	30–100 % of the info column. ✅ Default 100. Applies when Full width = off.
🔧 Quantity match button width (qty_match_button_width)	When inline layout, qty input takes equal width to the ATC button (so the row reads as two-equal columns). ✅ Default off.
🔧 Alignment (alignment)	left / center / right. ✅ Default left.

Per-control glow + shadow — each control (quantity selector, Add-to-cart, Buy-now/dynamic-checkout) has its own glow + shadow + glow-source trio, all ✅ default off:

Setting	What it does
🔧 Qty / ATC / Buy-now glow (qty_glow · atc_glow · buynow_glow)	Adds a soft glow around that control.
🔧 …glow source (qty_glow_source · atc_glow_source · buynow_glow_source)	accent (theme accent) / button (the button’s own color). ✅ Default accent. Visible only when the matching glow is on.
🔧 Qty / ATC / Buy-now shadow (qty_shadow · atc_shadow · buynow_shadow)	Adds a drop shadow to that control.

The block emits a --ne-pd-btn-width CSS-var on its <form> so other product blocks (e.g., wishlist with sync_with_buy_buttons) can match the ATC width.

Gift-card recipient — when the product is a gift card, this block automatically shows an “I want to send this as a gift” toggle. Turning it on reveals recipient email, recipient name, a message (200 characters max) and an optional send-on date, so the buyer can deliver the gift card straight to someone else. The fields only submit when the toggle is on. No setting required — it appears automatically for gift-card products.

Product-pickup (product-pickup)

Shows local pickup availability for the selected variant (“Pickup available at [location]” + estimated ready time) with a “View store information” toggle that lists every pickup location and its address. Updates automatically when the shopper changes variant. It renders only when the store has local pickup enabled for a location in Settings → Shipping and delivery; on stores without pickup it shows nothing. No block settings — placement only.

Product-description (product-description)

The product description (rich-text from Shopify Admin → Product → Description field).

Setting	What it does
🔧 Font role (font_role)	body / subheading / heading / accent. ✅ Default body. Pulls the font family from a theme typography role.
🔧 Display mode (mode)	full (always show all) / show-more (truncate with expand button) / scroll (max-height with internal scroll). ✅ Default full.
🔧 Preview lines (preview_lines)	2–12. ✅ Default 4. Number of lines shown before the truncation cuts in (show-more) or before the scroll-mask appears (scroll). Visible only when mode ≠ full.

✅ show-more is best for long descriptions — keeps the above-fold area clean, lets curious visitors expand. ✅ scroll is good for very long descriptions where you want a contained reading area instead of pushing later blocks far down the page.

Product-tabs (product-tabs)

Up-to-3 tabbed content panels — typically Description / Specs / Shipping & Returns, or Description / Reviews / FAQ.

Setting	What it does
🔧 Tab style (tab_style)	underline (active tab has an accent underline) / square (active tab has a filled square chip) / pill (active tab has a filled pill chip). ✅ Default underline.
🔧 Square corner radius (square_corner_radius)	0–24 px. ✅ Default 0. Visible only when tab_style = square.

Tabs 1–3 — each tab has the same 4 settings:

Setting	What it does
🔧 Tab label (tab1_label, tab2_label, tab3_label)	Tab heading text. ✅ Tab 1 default “Description”. Empty label → tab is hidden.
🔧 Content source (tab1_source, etc.)	description (auto-pulls Shopify product.description) / richtext (use the inline rich-text field below) / page (embed a Shopify Page’s content). ✅ Tab 1 default description.
🔧 Content (tab1_content, etc.)	Rich-text editor. Only visible when source = richtext.
🔧 Page (tab1_page, etc.)	Shopify Page picker. Only visible when source = page.

The tabs are inline schema settings, not child blocks. You can’t have more than 3 tabs — that’s the design ceiling. Set an empty label to hide a tab.

Product-collapsible (product-collapsible)

A single collapsible row — typically “Shipping & returns” or a care-instructions panel. For multiple stacked accordions, use the Collapsible Content section (§10.8).

Setting	What it does
🔧 Heading (heading)	Row label. ✅ Default “Shipping & returns”.
🔧 Icon (icon)	none / truck / shield / refresh / info / leaf / star / question / plus / check / custom (library icon set; custom pairs with the Custom icon upload). ✅ Default truck.
🔧 Custom icon (custom_icon)	Image upload (SVG recommended) — overrides the library icon when set.
🔧 Icon color (icon_color)	Hex / rgba. Leave blank to inherit text color.
🔧 Content source (content_source)	richtext (inline rich-text below) / page (embed a Shopify Page). ✅ Default richtext.
🔧 Content (content)	Rich-text editor. Only visible when source = richtext.
🔧 Page (page)	Shopify Page picker. Only visible when source = page.
🔧 Open by default (open_by_default)	When on, the row is pre-expanded on page load. ✅ Default off.

Product-size-chart (product-size-chart)

A size-chart popup. Useful for apparel / footwear / accessories.

Setting	What it does
🔧 Trigger label (trigger_label)	Link / button text. ✅ Default “Size chart”.
🔧 Trigger style (trigger_style)	link (inline underlined text-link) / button (rendered as a secondary button). ✅ Default link.
🔧 Modal heading (modal_heading)	Title shown at the top of the popup. ✅ Default “Size chart”.
🔧 Content source (content_source)	richtext (inline rich-text — a table or measurements) / page (embed a Shopify Page — useful if you have one size chart shared across many products). ✅ Default richtext.
🔧 Content (content)	Rich-text editor. Only visible when source = richtext.
🔧 Page (page)	Shopify Page picker. Only visible when source = page.

Product-selling-plan (product-selling-plan)

Subscription / “subscribe and save” selector. Only renders if the product has selling plans configured in Shopify Admin (Plans created via the Subscriptions app).

Setting	What it does
🔧 Heading (heading)	Section label above the plan-selector. ✅ Default “Purchase options”.
🔧 Show savings (show_savings)	Display “Save 10 %” or similar next to each subscription option (Shopify calculates the discount). ✅ Default on.

Product-share (product-share)

Social-media share buttons. Each platform has its own toggle so you can show only the ones relevant to your audience.

Setting	What it does
🔧 Style (style)	icon (icons only) / text (platform-name text only) / icon-text (icon + label side-by-side). ✅ Default icon-text.
🔧 Alignment (alignment)	left / center / right. ✅ Default left.
🔧 Show native share (show_native_share)	Mobile browsers’ system share-sheet (iOS / Android) via the Web Share API. Falls back to a custom dropdown on desktop. ✅ Default on.
🔧 Native share label (label)	Custom label for the native share button. Leave blank for “Share”.
🔧 Show Facebook (show_facebook)	Open Facebook share dialog. ✅ Default off.
🔧 Show Twitter / X (show_twitter)	Open X compose with the product URL + title. ✅ Default off.
🔧 Show Pinterest (show_pinterest)	Open Pinterest pin-creator with the featured image. ✅ Default off.
🔧 Show WhatsApp (show_whatsapp)	Pre-filled WhatsApp message — great for mobile-first markets. ✅ Default off.
🔧 Show Email (show_email)	Open mail client with the product URL pre-filled. ✅ Default off.

Product-wishlist (product-wishlist)

Add-to-wishlist button. Only enabled if Theme settings → Wishlist → Enable wishlist is on.

Setting	What it does
🔧 Label mode (label_mode)	icon (heart icon only) / text (text only — no icon) / icon-text (icon + label side-by-side). ✅ Default icon-text.
🔧 Add label (label_add)	Text shown when the product is NOT yet in the wishlist. ✅ Default “Add to wishlist”.
🔧 Remove label (label_remove)	Text shown when the product IS in the wishlist. ✅ Default “Remove from wishlist”.
🔧 Sync with buy buttons (sync_with_buy_buttons)	When on, the wishlist button reads --ne-pd-btn-width from the Buy-Buttons block and matches its width. ✅ Default on.
🔧 Width (width)	30–100 %. Only visible when sync_with_buy_buttons = off. ✅ Default 100.
🔧 Alignment (alignment)	left / center / right. ✅ Default left.

Wishlist state is stored in localStorage (ne-wishlist). Adding a product saves its handle; removing toggles it off. The wishlist page (/pages/wishlist) reads from the same localStorage and renders product cards via JS.

7.3 Default product-page composition

The template templates/product.json ships with this block arrangement:

sections/product.liquid
├─ product-vendor
├─ product-title
├─ product-price
├─ product-variant-picker
├─ product-buy-buttons
├─ product-pickup
├─ product-wishlist
├─ product-description
└─ product-share

You can reorder, remove, or add blocks freely. A typical luxury / fashion store might add product-tabs and product-size-chart. A subscription store would add product-selling-plan. A specs-heavy electronics store might use product-tabs for Description / Specs / Reviews.

7.4 Recently Viewed (recently-viewed)

A wrapper section for a grid of products the visitor has previously viewed (localStorage-tracked via key ne-recently-viewed, capped at the most recent 24 handles). Like Gallery / Video / Map in chapter 6, the section is a thin @theme container — all the grid UI (columns, card surface, hover effect, badges, quick-add, etc.) lives on the recently-viewed-grid BLOCK that you drop inside.

Available on: product / collection / index / page / cart / blog / article / search templates.

Section-specific settings

Setting	What it does
🔧 Max width	Range 600–1800px, step 20. ✅ Default 1400px.
🔧 Content gap	Range 0–80px, step 4. ✅ Default 32px.
🔧 Content alignment	Left (✅ default) / Center / Right — applies to heading/text blocks beside the grid.

Effects + chrome + color scheme

Standard v7 chrome (Transparent bg, Glass, Glass tint, Drop shadow, Accent glow, Use global scheme + dark/light pair, Full width + full width mobile, Padding top + bottom, Radius, Hide on mobile/desktop). See chapter §2 and §3.

Blocks accepted

recently-viewed-grid · heading · text · button · group · image · icon · divider · spacer

The grid settings (max products, columns, image ratio, card surface, etc.) live on the recently-viewed-grid block — see §7.8.

Empty-state behaviour

⚠️ The section is invisible to first-time visitors (empty recently-viewed list). Either accept this (most stores prefer this over an awkward “we have no idea what you’ve seen” header), or use a heading block with text that makes sense empty (e.g. “Browse our products”). The grid block also has a Hide when empty toggle to collapse the section entirely.

7.5 Related Products (related-products)

A wrapper section for a grid of products related to the currently displayed product. Powered by Shopify’s Recommendations API (/recommendations/products?product_id={id}&intent=related). The section is a thin @theme container — the grid configuration (intent, max products, columns, card surface, etc.) lives on the related-products-grid BLOCK.

Available on: product template only (the recommendations API needs a current product context).

Section-specific settings

Same as Recently Viewed (§7.4): max_width (600-1800px, default 1400) + content_gap (0-80px, default 32) + content_alignment (left/center/right, default left).

Effects + chrome + color scheme

Standard v7 chrome.

Blocks accepted

related-products-grid · heading · text · button · group · image · icon · divider · spacer

The grid renders via <section id>?section_id={id} AJAX-section-rendering: the page-load returns an empty grid skeleton, then JS fetches the section pre-populated with recommendations from the API and swaps the inner HTML — keeping initial page load fast even when the Recommendations API is slow. Recommendations intent + fallback behaviour are configured on the related-products-grid block — see §7.8.

7.5a Complementary Products (complementary-products)

A wrapper section for a “Pairs well with” / “Complete the look” grid, powered by Shopify’s Recommendations API with intent=complementary. Merchants curate which products are complementary in the free Shopify Search & Discovery app (Product relationships → Complementary products). Structurally identical to Related Products (§7.5) — same related-products-grid block, same card styling, same v7 chrome — the only difference is the recommendation intent.

Available on: product template only.

If no complementary products are configured for a product, the section hides itself automatically so the page never shows a stray fallback grid.

Section-specific settings

Same as Related Products (§7.5): max_width + content_gap + content_alignment, plus standard v7 chrome.

Blocks accepted

related-products-grid · heading · text · button · group · image · icon · divider · spacer

Default composition: a heading (“Pairs well with”) + a related-products-grid. Tip: place this section alongside Related Products on the product template to offer both “similar” and “goes-with” recommendations.

7.6 Wishlist (wishlist)

A wrapper section for a grid of products the visitor has saved to their wishlist (localStorage-tracked via key ne-wishlist). The section is a thin @theme container; the grid UI (columns, empty-state, quick-add, etc.) lives on the wishlist-grid BLOCK.

Available on: any template (no enabled_on restriction). Typically used on /pages/wishlist (Hyprism ships templates/page.wishlist.json for this).

Section-specific settings

Same as Recently Viewed (§7.4): max_width (600-1800px, default 1400) + content_gap (0-80px, default 32) + content_alignment (left/center/right, default left).

Effects + chrome + color scheme

Standard v7 chrome.

Blocks accepted

wishlist-grid · heading · text · button · group · image · icon · divider · spacer

Configure the empty-state heading + CTA, remove-button visibility, quick-add behaviour on the wishlist-grid block — see §7.8.

7.7 Smart product-card defaults

Every product card across the theme reads from snippets/product-card.liquid — a single Liquid snippet that the various grid blocks {% render %}. The card-render snippet handles:

Visual settings driven by theme-wide Layout → Product cards (§2.9)

• Badge shape (badge_shape)
• Badge position (badge_position)
• Badge size (badge_size)
• Sale badge label format (badge_label_format — percent / absolute / text)
• New-badge visibility + window (badge_show_new + badge_new_days + badge_show_both)
• Quick-add master toggle (enable_quick_add — see §2.9)

Per-block settings (forwarded by the grid block)

Each parent grid block (product-grid, recently-viewed-grid, related-products-grid, wishlist-grid) forwards its own settings (image ratio, title lines, card surface, card radius, card padding, vendor visibility, swatches, quick-view trigger, etc.) into the snippet as render parameters.

Wishlist heart

The wishlist heart button on every card is gated by Theme settings → Wishlist (§2.10) — toggle enable_wishlist + enable_product_wishlist_btn. Heart position + style + active color also come from there.

Quick view trigger

The quick-view trigger button on every card is gated by Theme settings → Quick view (§1.13) — toggle enable_quick_view. Trigger style / position / glass surface also come from there.

Unit price

When a product has a unit-price measurement (e.g. “$5.00/100ml” for products sold by weight or volume — required in some regions), the card automatically shows the unit price under the regular price. It appears only for products that carry a unit-price measurement; ordinary products show nothing extra. The same unit price also appears on the product page, in the cart, and on the customer’s order page.

CSS variables emitted on each card

The snippet emits per-card CSS variables for the parent’s per-block overrides: --ne-card-radius, --ne-card-padding, --ne-card-title-price-gap, --ne-card-title-font, --ne-card-title-weight, --ne-card-title-style, --ne-card-title-lines. These cascade into the card’s CSS rules — so per-instance overrides work without re-defining the whole card class.

So merchants configure badges once at theme-level (§2.9), tone wishlist + quick-view once (§2.10, §1.13), and tweak per-section card style per grid block — and every product card stays consistent.

7.8 Grid blocks — recently-viewed-grid, related-products-grid, wishlist-grid

These three blocks render the product grids inside their respective sections (7.4 Recently Viewed, 7.5 Related Products, 7.6 Wishlist). All three share a similar settings surface because they all render product cards — different data source, same UI.

The three blocks are NOT inter-changeable but the settings explained below are common to all three (with block-specific extras called out).

Common settings — grid layout

Setting	What it does
🔧 Columns (desktop)	Range 2–6, step 1. ✅ Default 4.
🔧 Columns (mobile)	1 or 2 (✅ default).
🔧 Gap	Range 4–40px, step 2. ✅ Default 16px.
🔧 Products count	Range varies by block — recently-viewed: 2–24 (default 8), related-products: 2–12 (default 4). Wishlist has no products_count setting — shows ALL saved products.

Common settings — card content

Setting	What it does
🔧 Image ratio	Square (✅ default on all three grids) / Natural / Portrait / Landscape. Only 4 options — no named 4:5 / 2:3 / 16:9 here (use product-grid block §8.5 for those).
🔧 Title lines	Range 0–4, step 1. ✅ Default 2. Titles clamp with ellipsis when longer. 0 = unlimited.
🔧 Title font role	Inherit (✅ default) / Body / Subheading / Heading / Accent.
🔧 Title bold	✅ Default off. Forces font-weight 700.
🔧 Title italic	✅ Default off. Forces italic.
🔧 Title-price gap	Range 0–32px, step 1. ✅ Default 8px.
🔧 Show vendor	✅ Default off.
🔧 Show secondary image on hover	✅ Default on. Reveals product’s 2nd image on hover.
🔧 Show swatches	✅ Default on. Only on related-products-grid (and product-grid block) — not on recently-viewed-grid or wishlist-grid.
🔧 Enable quick view	✅ Default on. Only on related-products-grid (and product-grid block) — not on recently-viewed-grid (designed for repeat-purchase context, no need for a re-discovery modal) or wishlist-grid (uses Quick Add instead).
🔧 Show remove button	✅ Default on. Only on wishlist-grid.
🔧 Enable quick add	✅ Default on. Only on wishlist-grid. Single-variant adds directly to cart; multi-variant opens variant-picker popup.
🔧 Enable add to cart (enable_add_to_cart)	✅ Default off. Only on related-products-grid. Adds a quick-add button (single-variant direct / multi-variant popup).
🔧 Add to cart label	✅ Default Add to cart. Only on wishlist-grid.

Common settings — card style

Setting	What it does
🔧 Card surface	Solid (✅ default — scheme bg) / Transparent / Glass.
🔧 Tint glass with accent (card_glass_tint)	Tints the glass cards with the scheme accent (strength = Effects → Glass tint intensity). ✅ Default off. Only visible when Card surface = Glass. (Applies to all three grids, incl. the wishlist quick-add popup.)
🔧 Card radius	Range 0–48px, step 2. ✅ Default 12px.
🔧 Image radius	Range 0–48px, step 2. ✅ Default 0. Separate from card radius.
🔧 Card padding	Range 0–24px, step 2. ✅ Default 0.
🔧 Card shadow	✅ Default off.
🔧 Card glow	✅ Default off.

Common settings — color scheme

Wishlist-grid has a per-block scheme override (use_custom_scheme + card_color_scheme + dark/light pair). Related-products-grid has a single-scheme override (use_global_scheme + color_scheme, no dark/light pair). Recently-viewed inherits the parent section’s scheme.

Block-specific settings

recently-viewed-grid:

• 🔧 Show compare price — ✅ Default on. Display the original “was X” struck-through price.
• 🔧 Exclude current product — ✅ Default on. When viewing a product, skip it in the list.
• 🔧 Hide when empty — ✅ Default on. Hide the entire section if no recently-viewed products.
• 🔧 Empty text — ✅ Default No recently vi…. Fallback text when not hidden.

related-products-grid:

• 🔧 Hide when empty — ✅ Default on. Hide entire section if Recommendations API returns no products.

wishlist-grid:

• 🔧 Empty text — ✅ Default Your wishlist …. Heading when no wishlisted products.
• 🔧 Continue shopping label — ✅ Default Continue shopping.
• 🔧 Continue shopping URL — URL picker (typically /collections/all).

Use rule of thumb

Wherever you place a Recently-Viewed, Related-Products, or Wishlist section, the corresponding grid block is auto-rendered inside it. You typically don’t need to add these blocks manually — they’re the section’s content. But you CAN configure their settings independently (per section instance) if you want different card-styles in different places.

Next

Chapter 8 — Collection and listing sections — the collection page, featured collection, collection lists.