Section reference
Mercer has 34 addable sections: 31 template sections and 3 section-group sections (Header, Footer, and Mobile bottom navigation). Availability depends on the template or group. The tables below list each addable section’s settings in schema order, using the Editor’s labels and the internal IDs in parentheses. Defaults are schema defaults; installed styles can supply different values. Template-specific sections and internal rendering endpoints are listed separately.
For background on what a section is and how it relates to blocks and templates, see Theme Editor walkthrough.
Categories
- Hero sections — seven designed heroes: the editorial magazine cover (Mercer’s default hero) plus the six signature heroes (including two designed for Confetti and a heritage masthead).
- Content sections — image with text, multi-column, testimonials, pull-quote, editorial story, image hotspot, lookbook, before / after, press coverage, collection navigation, promo sections, FAQ, newsletter, featured collection, featured blog, slideshow, video, and page-numbered grid.
- Product and collection sections — featured product, B2B quick order, related products, recently viewed.
- Custom Liquid section — for embedded HTML / Liquid.
- Chrome sections — Header, Footer, Mobile bottom navigation, plus the separately configured promo popup.
- Template-specific sections —
main-*sections that drive each template.
Hero sections
These are seven separate sections, not seven variants of one hero. They can be used with any style. Magazine cover hero is available on home, page, and collection templates; the six signature sections support all JSON templates. The installed style supplies its starting composition; changing Style accents does not replace its hero.
Magazine cover hero (hero-magazine-cover)
Mercer’s flagship hero. A masthead row (left / center / italic / right labels), a large image with an overlapping headline, optional page number, and an optional numbered “in-this-issue” index strip (off by default). Designed for editorial fashion / beauty.
| Setting | Type | Options and notes |
|---|---|---|
Masthead — left (masthead_left) | text | Issue-style label, e.g. “Vol. XVII” or “No. 04”. |
Masthead — center (italic) (masthead_center) | text | Edition title, e.g. “Editorial Review”. |
Masthead — right (masthead_right) | text | Edition label, e.g. “Studio Edition”. |
Masthead rule weight (rule_weight) | range | 1–4 px; step 1. Default: 2. |
Headline (headline) | richtext | Use the rich-text editor’s italic formatting for emphasis. Renders as the page’s H1 only when this is the first section on the home page; elsewhere it is an H2. |
Hero image (image) | image_picker | 3:2 aspect ratio recommended. Image crops to 4:3 on mobile. 1800 x 1200px recommended. |
Image alt text (image_alt) | text | Describe what the image shows. Leave blank to inherit from media library. |
Headline overlap (desktop) (headline_overlap) | select | Small (32 px) / Medium (56 px) / Large (72 px). Default: Medium (56 px). How far the headline drops below the image on desktop. |
Show page-number badge (show_page_no) | checkbox | Default: off. |
Badge text (page_no_label) | text | Cover page badge, e.g. “p. 01”. |
Show index strip below hero (show_index_strip) | checkbox | Default: off. |
Image overlay opacity (overlay_opacity) | range | 0–100 %; step 5. Default: 0. Fades the image toward the section’s background color so the headline stays readable over busy or high-contrast photos. 0% leaves the image untouched. |
Overlay style (overlay_style) | select | Solid / Gradient. Default: Gradient. |
Section color scheme (color_scheme) | select | Default / Editorial dark / Warm neutral / Accent pop / Soft contrast. Default: Default. Applies a named color palette to this section only. “Default” matches the rest of the store. |
Blocks: up to 8 Index item blocks. Each block has Page number, Heading, Link.
Pairs best with: Mercer preset.
Heritage · masthead (signature-heritage-masthead)
A heritage-feel section: established date, oversized title, hairline
- thick rules above and below, an image, and an attached product display with up to 12 ledger rows (“Material — Wool”, “Origin — Portugal”, “Construction — Hand-finished”).
Best for brands with a heritage / craftsmanship story.
Blocks: up to 12 Ledger row blocks, plus @app and Custom Liquid.
| Setting | Type | Options and notes |
|---|---|---|
Established line (established) | text | — |
House wordmark (masthead_title) | text | — |
Tagline (tagline) | text | — |
Outer rule weight (rule_weight_strong) | range | 1–4 px; step 0.5. Default: 2.5. |
Inner rule weight (rule_weight_hair) | range | 0.5–1.5 px; step 0.5. Default: 0.5. |
Featured product (product) | product | — |
Image override (image) | image_picker | Defaults to the product’s featured image. |
Image alt text (image_alt) | text | — |
Product caption (product_eyebrow) | text | — |
Product heading override (product_title) | text | — |
Price override (price_override) | text | Defaults to the product’s price. |
Label (cta_label) | text | — |
Link (cta_link) | url | Defaults to the product page. |
Section color scheme (color_scheme) | select | Default / Editorial dark / Warm neutral / Accent pop / Soft contrast. Default: Default. Applies a named color palette to this section only. “Default” matches the rest of the store. |
Luxe · single product (signature-luxe-singleproduct)
A single-product, very-spaced layout. Volume number, large italic pull-quote, an uppercase, letter-spaced attribution, an image, product title + meta + CTA. Up to 8 spec rows (label / value).
Best for fragrance / fine-jewelry feel.
Blocks: up to 8 Spec row blocks, plus @app and Custom Liquid.
| Setting | Type | Options and notes |
|---|---|---|
Volume / collection label (volume_no) | text | — |
Pull quote (quote) | richtext | — |
Attribution (attribution) | text | — |
Caption letter-spacing (caption_tracking) | range | 20–60 %; step 5. Default: 50. Higher values increase spacing. Applies to the volume label and attribution. |
Featured product (product) | product | — |
Image override (image) | image_picker | Defaults to the product’s featured image. |
Image alt text (image_alt) | text | — |
Heading override (product_title) | text | Defaults to product heading. Use line breaks for stacked typography. |
Meta line override (product_meta) | text | Defaults to product price. Example: “Eau de parfum / 50 ml · $210”. |
Label (cta_label) | text | — |
Link (cta_link) | url | Defaults to the product page. |
Section color scheme (color_scheme) | select | Default / Editorial dark / Warm neutral / Accent pop / Soft contrast. Default: Default. Applies a named color palette to this section only. “Default” matches the rest of the store. |
Color block (signature-pop-colorblock)
Stacked color blocks. Each block has its own foreground / background color (literal panel colors, not theme-wide tokens). Each block has caption / title / subtitle / image / CTA, plus a “side” toggle to flip image alignment.
Best for high-energy DTC beauty.
| Setting | Type | Options and notes |
|---|---|---|
Image rotation amount (rotation_amount) | range | 0–9 °; step 1. Default: 6. Alternates positive/negative per block. 0 = no rotation. |
Section color scheme (color_scheme) | select | Default / Editorial dark / Warm neutral / Accent pop / Soft contrast. Default: Default. Applies a named color palette to this section only. “Default” matches the rest of the store. |
Blocks: up to 8 Color block blocks. Each block has bg_color,
fg_color, eyebrow, title, subtitle, image, image_alt, cta_label,
cta_link, side. Plus @app and Custom Liquid.
Product scroller (signature-pop-hscroller)
Horizontal scrolling products from a chosen collection. Five background / ink pairs repeat by card position; the backgrounds do not animate or auto-rotate.
Each card uses its assigned literal tone colors. These can override the section color scheme; edit the tone pairs to coordinate them with your palette.
| Setting | Type | Options and notes |
|---|---|---|
Heading (heading) | richtext | Wrap the accent word in <em>…</em> to use the accent color. |
Collection (collection) | collection | — |
Products to show (product_limit) | range | 3–16; step 1. Default: 8. |
Tone 1 — background (tone_1_bg) | color | — |
Tone 1 — text (tone_1_ink) | color | — |
Tone 2 — background (tone_2_bg) | color | — |
Tone 2 — text (tone_2_ink) | color | — |
Tone 3 — background (tone_3_bg) | color | — |
Tone 3 — text (tone_3_ink) | color | — |
Tone 4 — background (tone_4_bg) | color | — |
Tone 4 — text (tone_4_ink) | color | — |
Tone 5 — background (tone_5_bg) | color | — |
Tone 5 — text (tone_5_ink) | color | — |
Section color scheme (color_scheme) | select | Default / Editorial dark / Warm neutral / Accent pop / Soft contrast. Default: Default. Applies a named color palette to this section only. “Default” matches the rest of the store. |
Specification strip (signature-tech-specstrip)
Designed for the Gridline preset. Terminal-style nav path, a desktop status-line text, an image with configurable reticle annotations, kicker / heading / body, two CTAs, and up to six label / value spec cells along the bottom. It inherits the active palette; its dark appearance comes from the Gridline style, not a separate dark default or a live launch-status indicator.
| Setting | Type | Options and notes |
|---|---|---|
Prompt path (path) | text | — |
Tagline or status line (timestamp) | text | Shows on desktop only. |
Hero image (image) | image_picker | — |
Image alt text (image_alt) | text | — |
Show placeholder media (show_placeholder_media) | checkbox | Default: off. Shows sample artwork until you select media. |
Image caption (filename style) (image_caption) | text | — |
Kicker line (kicker) | text | — |
Heading (heading) | richtext | Renders as the page’s H1 only when this is the first section on the home page; elsewhere it is an H2. |
Body (body) | richtext | — |
Label (cta_primary_label) | text | — |
Link (cta_primary_link) | url | — |
Label (cta_secondary_label) | text | — |
Link (cta_secondary_link) | url | — |
Section color scheme (color_scheme) | select | Default / Editorial dark / Warm neutral / Accent pop / Soft contrast. Default: Default. Applies a named color palette to this section only. “Default” matches the rest of the store. |
Blocks: up to 8 Navigation item blocks (label / link) for the
terminal-style nav path, up to 6 Spec cell blocks (label / value /
description), up to 6 Image reticle blocks (short labels placed on the
image by top / left percentage),
plus @app and Custom Liquid.
Warm · collections (signature-warm-collections)
Designed for Tactility. Optional announcement bar above the section, then a 2 / 3 / 4-column collection grid with rounded card corners and soft drop shadows and an italic heading. Each collection card has an image, title, product-count label, and link; it does not have material/origin captions.
| Setting | Type | Options and notes |
|---|---|---|
Show announcement bar (show_announcement) | checkbox | Default: on. |
Message (announcement_text) | text | — |
Caption (eyebrow) | text | — |
Heading (heading) | richtext | — |
Card corner radius (card_radius) | range | 16–32 px; step 2. Default: 24. Forced ≥ 16 per design — softer than other presets’ default radius. |
Image corner radius (image_radius) | range | 8–24 px; step 2. Default: 16. |
Columns (desktop) (columns_desktop) | select | 2 / 3 / 4. Default: 4. |
Columns (mobile) (columns_mobile) | select | 1 / 2. Default: 2. |
Section color scheme (color_scheme) | select | Default / Editorial dark / Warm neutral / Accent pop / Soft contrast. Default: Default. Applies a named color palette to this section only. “Default” matches the rest of the store. |
Blocks: up to 8 Collection card blocks (collection picker, title
override, image override, count label, link), plus @app and Custom Liquid.
Content sections
Image with text (image-with-text)
Two-column section with an image on one side and text on the other. Workhorse content section.
| Setting | Type | Options and notes |
|---|---|---|
Image (image) | image_picker | — |
Image alt text (image_alt) | text | — |
Show placeholder media (show_placeholder_media) | checkbox | Default: off. Shows sample artwork until you select media. |
Image ratio (image_ratio) | select | Square / Portrait (4:5) / Portrait (3:4) / Landscape (4:3). Default: Portrait (4:5). |
Image position (desktop) (image_position) | select | Left / Right. Default: Left. |
Text vertical alignment (vertical_align) | select | Top / Middle / Bottom. Default: Middle. |
Text alignment (text_align) | select | Start / Center / End. Default: Start. |
Use custom spacing (custom_spacing) | checkbox | Default: off. |
Top padding (padding_top) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Bottom padding (padding_bottom) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Background tone (tone) | select | Default (background) / Surface alt (warm tint) / Ink (inverted). Default: Default (background). |
Blocks (mix and match):
- Heading — large display text.
- Body — body copy.
- Caption — small label or eyebrow text.
- Button — label + link + style (Primary / Secondary / Ghost; default Secondary).
- Custom Liquid — embed arbitrary Liquid below the text.
@app— third-party app block.
Multi-column (multi-column)
A row of 2–4 columns each with an icon or image, heading, body, and optional link. Up to six Column blocks can occupy the 2–4 desktop columns. Great for value-prop / feature-callout rows.
| Setting | Type | Options and notes |
|---|---|---|
Caption (eyebrow) | text | — |
Heading (heading) | text | — |
Columns (desktop) (columns) | select | 2 / 3 / 4. Default: 3. |
Mobile layout (mobile_layout) | select | Stack vertically / Snap-scroll horizontally. Default: Stack vertically. |
Column alignment (text_align) | select | Center / Start. Default: Center. |
Use custom spacing (custom_spacing) | checkbox | Default: off. |
Top padding (padding_top) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Bottom padding (padding_bottom) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Background tone (tone) | select | Default / Surface alt / Ink (inverted). Default: Default. |
Blocks: one block per column, each with icon (preset SVG name),
image (overrides icon if set), heading, body, link_label, link_url. Also accepts
@app and Custom Liquid.
Testimonials (testimonials)
Customer quotes section. Shows one quote at a time, in one of two display modes: a single static quote, or a rotating quote with prev/next buttons (no autoplay).
| Setting | Type | Options and notes |
|---|---|---|
Caption (eyebrow) | text | — |
Heading (heading) | text | — |
Display mode (display_mode) | select | Single quote / Rotating with buttons (no autoplay). Default: Single quote. Rotating mode shows previous/next buttons; it does not advance automatically. |
Use custom spacing (custom_spacing) | checkbox | Default: off. |
Top padding (padding_top) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Bottom padding (padding_bottom) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Background tone (tone) | select | Default / Surface alt / Ink (inverted). Default: Surface alt. |
Blocks: one Quote block per testimonial (capped at 8), each
with quote, author, meta (e.g. “Verified buyer”, or a star count, or a
publication name). The section also accepts @app and Custom Liquid
blocks. Until a Quote block has text (or the section has an app or Custom
Liquid block), the section shows a setup hint in the Theme Editor and nothing
on the live storefront.
Pull-quote (pull-quote)
A single editorial pull-quote with attribution and an optional source link. Built for the Poise preset’s editorial pacing but enabled on every JSON template.
| Setting | Type | Options and notes |
|---|---|---|
Quote (quote) | richtext | — |
Attribution name (attribution_name) | text | — |
Source / publication (attribution_meta) | text | Optional. e.g., Wallpaper No. 248 |
Source link (source_link) | url | — |
Text alignment (text_align) | select | Start / Center. Default: Center. |
Use custom spacing (custom_spacing) | checkbox | Default: off. |
Top padding (padding_top) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Bottom padding (padding_bottom) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Background tone (tone) | select | Default (background) / Surface alt (warm tint) / Ink (inverted). Default: Default (background). |
Until the quote is filled in, the section shows a setup hint in the Theme Editor and nothing on the live storefront. The source link goes on the source / publication text, or on the attribution name when there is no source; with neither, it appears as a separate “Visit publication” link.
Distinct from Testimonials (which collects multiple short voices) — Pull-quote is a single larger prose-led quote that acts as a magazine pull-quote inside the page rhythm.
Editorial story (quiet-luxe-story)
A pure-typography editorial column — heading, body copy, and an optional attribution line below a hairline divider. Drops the image side that Image with text carries; widens the type column to a 60-character reading measure. Built for the Poise preset but enabled on every JSON template.
| Setting | Type | Options and notes |
|---|---|---|
Caption (eyebrow) | text | — |
Heading (heading) | text | — |
Body (body) | richtext | — |
Attribution (attribution) | text | Small label below a hairline divider, e.g., From the atelier journal |
Text alignment (text_align) | select | Start / Center. Default: Start. |
Use custom spacing (custom_spacing) | checkbox | Default: off. |
Top padding (padding_top) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Bottom padding (padding_bottom) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Background tone (tone) | select | Default (background) / Surface alt (warm tint) / Ink (inverted). Default: Default (background). |
Distinct from Image with text — Editorial story has no image side and reads as a typography-only editorial column.
Image hotspot (image-hotspot)
Large image with positioned markers. Desktop opens popovers from each marker; mobile and no-JS render the same content as a numbered list below the image. Markers use WAI-ARIA labels and the list fallback keeps hotspot content reachable without JavaScript.
| Setting | Type | Options and notes |
|---|---|---|
Subheading (subheading) | text | — |
Heading (heading) | text | — |
Body (body) | richtext | — |
Image (image) | image_picker | — |
Image alt text (image_alt) | text | — |
Show placeholder media (show_placeholder_media) | checkbox | Default: off. Shows sample artwork until you select media. |
Image ratio (image_ratio) | select | 16:9 / 4:5 / 3:4 / 1:1. Default: 4:5. |
Padding (px) (padding_block) | range | 24–96 px; step 8. Default: 64. |
Section color scheme (color_scheme) | select | Default / Editorial dark / Warm neutral / Accent pop / Soft contrast. Default: Default. Applies a named color palette to this section only. “Default” matches the rest of the store. |
Blocks: up to 12 Hotspot blocks. Each block sets x_position /
y_position, marker label, heading, rich text, link type (url,
product, collection, page), the matching link picker, and
cta_label.
Pairs best with: Lookbook, Before / after, Featured collection.
Lookbook (lookbook)
Editorial image grid for complete looks. The layout can be mosaic,
editorial_split, or stacked_story. Each tile can be a narrative
image, a linked image, or a shoppable image with up to three product
chips selected directly from product picker settings.
| Setting | Type | Options and notes |
|---|---|---|
Subheading (subheading) | text | — |
Heading (heading) | text | — |
Body (body) | richtext | — |
Show placeholder media (show_placeholder_media) | checkbox | Default: off. Shows sample artwork until you select media. |
Layout style (layout) | select | Mosaic grid / Editorial split / Stacked story. Default: Mosaic grid. Mosaic uses an asymmetric grid, editorial split pairs each image with its caption, and stacked story is a single-column narrative. |
Tile gap (px) (tile_gap) | range | 0–48 px; step 4. Default: 16. |
Padding (px) (padding_block) | range | 24–96 px; step 8. Default: 64. |
Section color scheme (color_scheme) | select | Default / Editorial dark / Warm neutral / Accent pop / Soft contrast. Default: Default. Applies a named color palette to this section only. “Default” matches the rest of the store. |
Blocks: up to 12 Image tile blocks. Each tile has image, tile size
(regular / feature), eyebrow, heading, description, link type +
picker, optional button label, and product_chip_1 through
product_chip_3.
Pairs best with: Featured collection, Image hotspot, Promo tiles.
Before / after (before-after)
Image comparison section for transformations, fit comparisons, or
material before / after states. The enhanced control is a native
<input type="range">, so keyboard navigation works without custom
slider semantics. With JavaScript unavailable, the images stack below 700 px
and render side-by-side at 700 px and wider.
| Setting | Type | Options and notes |
|---|---|---|
Subheading (subheading) | text | — |
Heading (heading) | text | — |
Body (body) | richtext | — |
Image (before_image) | image_picker | — |
Image alt text (before_alt) | text | — |
Show placeholder media (show_placeholder_media) | checkbox | Default: off. Shows sample artwork until you select media. |
Label (before_label) | text | — |
Image (after_image) | image_picker | — |
Image alt text (after_alt) | text | — |
Label (after_label) | text | — |
Image ratio (image_ratio) | select | 16:9 / 4:3 / 1:1 / 4:5. Default: 4:5. |
Starting reveal position (start_position) | range | 0–100 %; step 5. Default: 50. Where the divider sits when the section first loads. |
Padding (px) (padding_block) | range | 24–96 px; step 8. Default: 64. |
Section color scheme (color_scheme) | select | Default / Editorial dark / Warm neutral / Accent pop / Soft contrast. Default: Default. Applies a named color palette to this section only. “Default” matches the rest of the store. |
Blocks: none.
Pairs best with: Image hotspot, Product education pages, FAQ.
Press coverage (press-coverage)
“As seen in” section for publication logos, quotes, and press links. If a logo is not set, the publication name renders as text. Only use publication logos you are licensed to display. The section is added with its caption and heading only; add a Press item block for each publication. Until a block has a logo, publication name, or quote, the section shows a setup hint in the Theme Editor and nothing on the live storefront. Blocks with none of these are skipped.
| Setting | Type | Options and notes |
|---|---|---|
Caption (eyebrow) | text | — |
Heading (heading) | text | — |
Use custom spacing (custom_spacing) | checkbox | Default: off. |
Top padding (padding_top) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Bottom padding (padding_bottom) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Background tone (tone) | select | Default / Surface alt / Ink (inverted). Default: Default. The inverted “Ink” tone paints the band in the text color — dark logo images drawn for light backgrounds can disappear on it. Use light or knockout logo versions there. |
Blocks: up to 12 Press item blocks. Each block has publication logo, logo alt text, publication name, quote, and link.
Pairs best with: Testimonials, Pull-quote, Editorial story.
Collection navigation (collection-navigation)
Navigation chips or columns for collection landing pages, editorial
collection directories, or home page category jumps. Source can be a
menu (source: menu) or a hand-picked collection list
(source: collections).
| Setting | Type | Options and notes |
|---|---|---|
Subheading (subheading) | text | — |
Heading (heading) | text | — |
Navigation source (source) | select | Navigation / Collection list. Default: Navigation. Choose whether the links come from a navigation menu or a hand-picked collection list. |
Navigation menu (link_list) | link_list | Used when the source is set to Navigation. Top-level links are shown as navigation. |
Show subcollections (show_subcollections) | checkbox | Default: on. When a menu link has child links, show them as a nested subcollection group. |
Collections (collection_list) | collection_list | Used when the source is set to Collection list. |
Show product count (show_count) | checkbox | Default: off. Display the number of products next to each collection. Collection list source only. |
Desktop layout (layout) | select | Chips (wrapping row) / Columns. Default: Chips (wrapping row). On screens under 768px both layouts collapse to a horizontal-scroll chip row. |
Use custom spacing (custom_spacing) | checkbox | Default: off. |
Top padding (padding_top) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Bottom padding (padding_bottom) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Background tone (tone) | select | Default (background) / Surface alt (warm tint) / Ink (inverted). Default: Default (background). |
Blocks: none.
Pairs best with: Collection grid, Featured collection, Promo tiles.
Promo banner (promo-banner)
Single promotional band with optional image, copy, CTA, and a merchant-
set countdown. Use countdowns only for real campaign end dates; the
theme never restarts expired countdowns automatically. If the end date can’t be
read — a typo or an impossible date such as 2026-02-30 — the banner shows
neither a countdown nor the ended message, and the Theme Editor shows a format
warning. An end time with an offset, such as 2026-12-31T23:59:00+02:00, uses
that offset; one without an offset is read as UTC.
| Setting | Type | Options and notes |
|---|---|---|
Image (image) | image_picker | — |
Image position (image_position) | select | Background / Left / Right / None. Default: Background. Background image displays full-bleed; place high-contrast text on top. |
Text alignment (text_alignment) | select | Start / Center / End. Default: Center. |
Height (height) | select | Auto / Small / Medium / Large. Default: Medium. |
Caption (eyebrow) | text | — |
Heading (heading) | text | — |
Body (body) | richtext | — |
Button label (button_label) | text | — |
Button link (button_link) | url | — |
Show countdown (countdown_enabled) | checkbox | Default: off. Countdowns must use a real merchant-set end date. Leave off unless the campaign has a true end time. |
Countdown end (countdown_end) | text | Use ISO 8601 format like 2026-12-31T23:59:00Z. Times are interpreted as UTC. |
When countdown expires (countdown_expired_action) | select | Hide countdown / Show ended message. Default: Hide countdown. Choose whether to hide the countdown or show a neutral ended message. Expired countdowns never restart automatically. |
Expired message (countdown_expired_message) | text | — |
Use custom spacing (custom_spacing) | checkbox | Default: off. |
Top padding (padding_top) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Bottom padding (padding_bottom) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Section color scheme (color_scheme) | select | Default / Editorial dark / Warm neutral / Accent pop / Soft contrast. Default: Default. Applies a named color palette to this section only. “Default” matches the rest of the store. |
Blocks: none.
Pairs best with: Featured collection, Promo tiles, Collection navigation.
Promo tiles (promo-tiles)
Grid of promotional tiles for campaign hubs, shopping paths, or editorial links. Tiles can link to external URLs, products, collections, or pages.
| Setting | Type | Options and notes |
|---|---|---|
Heading (heading) | text | — |
Subheading (subheading) | text | — |
Show placeholder media (show_placeholder_media) | checkbox | Default: off. Shows sample artwork until you select media. |
Desktop columns (columns_desktop) | select | 2 / 3 / 4. Default: 3. |
Tablet columns (columns_tablet) | select | 2 / 3. Default: 2. |
Mobile layout (mobile_layout) | select | Stacked / Horizontal scroll. Default: Horizontal scroll. |
Tile aspect ratio (tile_aspect) | select | 4:5 / 1:1 / 3:4 / 16:9. Default: 4:5. |
Overlay text on image (show_overlay) | checkbox | Default: off. |
Text alignment (text_alignment) | select | Start / Center / End. Default: Start. |
Padding (px) (padding_block) | range | 24–96 px; step 8. Default: 64. |
Section color scheme (color_scheme) | select | Default / Editorial dark / Warm neutral / Accent pop / Soft contrast. Default: Default. Applies a named color palette to this section only. “Default” matches the rest of the store. |
Blocks: up to 12 Tile blocks. Each block has image, heading,
description, badge, link type + picker, and cta_label.
Pairs best with: Collection navigation, Promo banner, Lookbook.
FAQ (faq)
Addable FAQ accordion section. It also ships in templates/page.faq.json
below the page content, so merchants can build a dedicated FAQ page
without custom Liquid.
| Setting | Type | Options and notes |
|---|---|---|
Subheading (subheading) | text | — |
Heading (heading) | text | — |
Intro text (intro_richtext) | richtext | — |
Layout (layout) | select | Single column / Two columns. Default: Single column. |
Allow multiple questions open at once (allow_multiple_open) | checkbox | Default: on. When disabled, opening a question closes the previous one in single-column layout. Two-column layout always allows multiple open to avoid grid layout shifts. |
Show category labels (show_category_labels) | checkbox | Default: on. |
Add FAQ structured data (emit_faq_jsonld) | checkbox | Default: on. Helps search engines understand these questions. Recommended on a dedicated FAQ page; turn off when this section is one of several FAQ areas on the same page. |
Use custom spacing (custom_spacing) | checkbox | Default: off. |
Top padding (padding_top) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Bottom padding (padding_bottom) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Section color scheme (color_scheme) | select | Default / Editorial dark / Warm neutral / Accent pop / Soft contrast. Default: Default. Applies a named color palette to this section only. “Default” matches the rest of the store. |
Blocks: Question blocks. Each block has category, question,
answer, and open_by_default.
Pairs best with: Product education pages, Support pages, Before / after.
Newsletter (newsletter)
Email signup. Posts to Shopify’s customer subscription endpoint via
the standard customer form drop. Includes consent checkbox + success
message. An optional image sits beside the form.
| Setting | Type | Options and notes |
|---|---|---|
Caption (eyebrow) | text | — |
Heading (heading) | text | — |
Body (body) | richtext | — |
Image (image) | image_picker | — |
Image alt text (image_alt) | text | — |
Image position (image_position) | select | Left / Right. Default: Left. |
Submit button label (submit_label) | text | — |
Require marketing consent checkbox (require_consent) | checkbox | Default: on. Shows a consent checkbox before shoppers can submit the form. Review your legal requirements before changing this setting. |
Consent text (consent_text) | text | — |
Success text (success_text) | text | — |
Use custom spacing (custom_spacing) | checkbox | Default: off. |
Top padding (padding_top) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Bottom padding (padding_bottom) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Background tone (tone) | select | Default / Surface alt / Ink (inverted). Default: Surface alt. |
Blocks: @app and Custom Liquid, for example a disclaimer below the form.
Featured collection (featured-collection)
A collection-grid hero. Surfaces a chosen collection’s first N products. Standard pattern for “Shop the look” / “New arrivals”.
| Setting | Type | Options and notes |
|---|---|---|
Caption (eyebrow) | text | — |
Heading (heading) | text | — |
Description (description) | textarea | — |
View-all button label (cta_label) | text | — |
Collection (collection) | collection | — |
Use all products if unavailable (fallback_to_all) | checkbox | Default: off. Uses the All collection only when the selected collection is missing or unavailable. An existing empty collection stays empty. |
Products to show (product_limit) | range | 2–16; step 1. Default: 8. |
Card style (card_variant) | select | Minimal — text only / Default — with color swatches / With badges (Sale / Sold out). Default: Minimal — text only. |
Show price (show_price) | checkbox | Default: on. |
Low-stock threshold (low_stock_threshold) | range | 0–20; step 1. Default: 0. 0 = off. When set and a product’s stock is at or below this number, an honest “Only X left” pill is shown. Requires inventory tracking. |
Columns (desktop) (columns_desktop) | select | 2 / 3 / 4. Default: 4. |
Columns (mobile) (columns_mobile) | select | 1 / 2. Default: 2. |
Use custom spacing (custom_spacing) | checkbox | Default: off. |
Top padding (padding_top) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Bottom padding (padding_bottom) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Section color scheme (color_scheme) | select | Default / Editorial dark / Warm neutral / Accent pop / Soft contrast. Default: Default. Applies a named color palette to this section only. “Default” matches the rest of the store. |
Page-numbered grid (collection-grid-paged)
A signature section: a single (non-paginated) collection grid where each card carries a decorative editorial mono page-number label (“p. 06”, “p. 08”, …) derived from the starting page and page step. These labels are purely typographic — there is no “Page 2 of 4 →” navigation. Often used as a home page element to surface a deep collection.
| Setting | Type | Options and notes |
|---|---|---|
Heading (heading) | text | — |
Subheading (subheading) | text | Editorial caption. Leave blank with “Show page range” on to auto-generate one from the page numbering below. |
Show page range (show_page_range) | checkbox | Default: off. When the subheading is blank, shows an auto-generated “Pages NN — NN” caption computed from the page numbering below, so it always matches the badges. |
Collection (collection) | collection | — |
Use all products if unavailable (fallback_to_all) | checkbox | Default: off. Uses the All collection only when the selected collection is missing or unavailable. An existing empty collection stays empty. |
Products to show (product_limit) | range | 2–12; step 1. Default: 6. |
Show price (show_price) | checkbox | Default: on. |
Columns (desktop) (columns_desktop) | select | 2 / 3 / 4. Default: 3. |
Columns (mobile) (columns_mobile) | select | 1 / 2. Default: 2. |
Starting page number (page_start) | range | 1–99; step 1. Default: 6. First “p. NN” badge in the grid; later products count up from here. |
Page step (between products) (page_step) | range | 1–6; step 1. Default: 2. How much each product’s “p. NN” badge increases over the previous one. |
Button label (cta_label) | text | — |
Button link (cta_link) | url | — |
Use custom spacing (custom_spacing) | checkbox | Default: off. |
Top padding (padding_top) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Bottom padding (padding_bottom) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Slideshow (slideshow)
A full-width rotating slideshow. Each slide carries its own image, mobile image, text overlay (subheading / heading / text), text color, text box, and CTA. Has presets and is enabled on every JSON template.
| Setting | Type | Options and notes |
|---|---|---|
Slide height (height) | select | Small / Medium / Large / Adapt to first image. Default: Medium. |
Vertical padding (padding_block) | range | 0–64 px; step 4. Default: 0. |
Content width (content_width) | select | Narrow / Standard / Wide. Default: Standard. |
Auto-rotate slides (autoplay) | checkbox | Default: off. Off by default. Auto-rotation is paused for visitors who prefer reduced motion and while the slideshow is hovered or focused. |
Change slides every (autoplay_interval) | range | 3–10 s; step 1. Default: 5. |
Transition (transition) | select | Slide / Fade. Default: Slide. |
Show previous/next arrows (show_arrows) | checkbox | Default: on. |
Show pagination dots (show_dots) | checkbox | Default: on. |
Slideshow label (accessibility_label) | text | Describes the slideshow for screen readers. When blank, screen readers hear the generic “Carousel” label in the storefront language, so give each slideshow on a page its own label. |
Control color scheme (color_scheme) | select | Default / Editorial dark / Warm neutral / Accent pop / Soft contrast. Default: Default. Recolors each slide’s primary button, the placeholder shown for a slide without an image, the hover color and focus ring of links in slide text, and the editor message shown before any slide is added. The arrows, dots, play/pause button and secondary button keep fixed styling. Each slide sets its own text color (Light / Dark) and image overlay opacity; the overlay itself is always black. |
With two or more slides, turning off both Show previous/next arrows and Show pagination dots still leaves previous/next arrows whenever the slides aren’t rotating automatically: with Auto-rotate slides off, for visitors who prefer reduced motion, or after the shopper pauses.
Blocks: up to 8 Slide blocks.
Video (video)
A video section that plays a hosted Shopify video or an external URL (YouTube / Vimeo), with an optional poster image and a text overlay.
| Setting | Type | Options and notes |
|---|---|---|
Video type (video_type) | select | Shopify-hosted / External (YouTube/Vimeo). Default: Shopify-hosted. |
Video (video) | video | Used when the video type is Shopify-hosted. |
Video URL (video_url) | video_url | Used when the video type is External. Supports YouTube and Vimeo. |
Poster image (poster) | image_picker | Shown before the video plays, and as a fallback when no video is set. |
Poster alt text (poster_alt) | text | Describes the poster image for screen readers. |
Autoplay (autoplay) | checkbox | Default: off. When on, the video plays muted and loops. Disabled for visitors who prefer reduced motion. |
Aspect ratio (aspect_ratio) | select | 16:9 (widescreen) / 4:3 / 1:1 (square) / 21:9 (cinematic) / Adapt to video. Default: 16:9 (widescreen). |
Overlay opacity (overlay_opacity) | range | 0–100 %; step 5. Default: 30. Darkens the video behind the overlay text for legibility. Only shown when text blocks are added. |
Text alignment (text_align) | select | Start / Center / End. Default: Start. |
Background tone (tone) | select | Default / Surface alt / Ink (inverted). Default: Default. |
Blocks: Caption, Heading, Body, Button, plus a
Custom Liquid block and @app.
Featured blog (featured-blog)
Surfaces the most recent posts from a chosen blog as a card grid. Good for a “From the journal” home-page row.
| Setting | Type | Options and notes |
|---|---|---|
Caption (eyebrow) | text | — |
Heading (heading) | text | — |
Description (description) | textarea | — |
View-all button label (cta_label) | text | — |
Blog (blog) | blog | — |
Posts to show (post_limit) | range | 2–12; step 1. Default: 3. |
Show featured image (show_image) | checkbox | Default: on. |
Show date (show_date) | checkbox | Default: on. |
Show excerpt (show_excerpt) | checkbox | Default: on. |
Show author (show_author) | checkbox | Default: off. |
Show tag (show_tag) | checkbox | Default: off. |
Columns (desktop) (columns_desktop) | select | 2 / 3 / 4. Default: 3. |
Columns (mobile) (columns_mobile) | select | 1 / 2. Default: 1. |
Empty heading (empty_title) | text | — |
Empty body (empty_body) | textarea | — |
Use custom spacing (custom_spacing) | checkbox | Default: off. |
Top padding (padding_top) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Bottom padding (padding_bottom) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Section color scheme (color_scheme) | select | Default / Editorial dark / Warm neutral / Accent pop / Soft contrast. Default: Default. Applies a named color palette to this section only. “Default” matches the rest of the store. |
Product and collection sections
Featured product (featured-product)
A full PDP-grade single-product section that can be embedded on the home (index) and page templates only. Includes rich media, variant picker, selling plans, the gift-card recipient flow when relevant, payment_button, Shop Pay Installments banner, and accelerated checkout. A View full details link under the product title opens the product page on the shopper’s selected variant and purchase option.
| Setting | Type | Options and notes |
|---|---|---|
Heading (heading) | text | — |
Description (description) | richtext | — |
Product (product) | product | — |
Show vendor (show_vendor) | checkbox | Default: off. |
Show variant picker (show_variant_picker) | checkbox | Default: on. |
Show quantity selector (show_quantity_selector) | checkbox | Default: on. |
Show restock request form for sold-out variants (show_back_in_stock_form) | checkbox | Default: on. |
Low-stock threshold (low_stock_threshold) | range | 0–20; step 1. Default: 5. 0 = off. Honest “Only N left” pill when stock is at or below this number. Only renders when inventory tracking is enabled and ‘continue selling when out of stock’ is off. |
Use custom spacing (custom_spacing) | checkbox | Default: off. |
Top padding (padding_top) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Bottom padding (padding_bottom) | range | 0–120 px; step 4. Default: 48. Used when Use custom spacing is on. |
Background tone (tone) | select | Default / Surface alt / Ink (inverted). Default: Default. |
The buy box is not composable. It renders a fixed layout driven by the section settings above (heading, description, product, show vendor / variant picker / quantity selector / back-in-stock form) plus the shared PDP snippets. It does not offer the Product section’s blocks, such as Price, Variant picker, Buy buttons, Description, Trust signal, Share row, or Accordion section.
Blocks: only @app and Custom Liquid.
B2B quick order (b2b-quick-order)
Merchant-addable order grid for signed-in B2B buyers. Buyers enter
quantities across multiple variants, then add selected rows to cart
in one Ajax action. The section self-gates on customer.b2b?; B2C
visibility can be hidden or a plain product list.
| Setting | Type | Options and notes |
|---|---|---|
Caption (eyebrow) | text | — |
Heading (heading) | text | — |
Description (description) | richtext | — |
Product source (source) | select | Collection / Selected products. Default: Collection. Pick which products fill the order grid. |
Collection (collection) | collection | — |
Products (product_list) | product_list | — |
Show SKU (show_sku) | checkbox | Default: on. |
Show inventory status (show_inventory) | checkbox | Default: off. Only shown for variants that track inventory. |
Show order quantity rules (show_quantity_rules) | checkbox | Default: on. Displays per-variant minimum, maximum, and increment rules when set. |
Show volume pricing (show_price_breaks) | checkbox | Default: on. Displays per-variant quantity price breaks when set. |
Show to non-B2B customers as (b2c_visibility) | select | Hidden / Plain product list. Default: Hidden. The quantity grid is always available to B2B customers. Choose what everyone else sees. |
Section color scheme (color_scheme) | select | Default / Editorial dark / Warm neutral / Accent pop / Soft contrast. Default: Default. Applies a named color palette to this section only. “Default” matches the rest of the store. |
The grid reuses Mercer’s existing quantity-rule and tier-table surfaces, then submits via Shopify’s native Ajax Cart path. It does not create quotes, draft orders, or PO workflows. See B2B for setup context.
Related products (related-products)
Renders related or complementary products. The complementary instance
is metafield-first; the related instance always uses Shopify’s
algorithmic Recommendations API.
| Setting | Type | Options and notes |
|---|---|---|
Heading (heading) | text | — |
Recommendation intent (intent) | select | Related (similar products) / Complementary (often bought together). Default: Related (similar products). |
Products shown (limit) | range | 2–10; step 1. Default: 4. |
Card style (card_variant) | select | Minimal / With color swatches / With badges. Default: Minimal. |
complementary intent is metafield-first: it reads the merchant-curated
product.metafields.custom.pairs_with list and renders it inline, falling
back to the algorithmic Recommendations API (/recommendations/products)
only when no curated list exists. related always reads the algorithmic
recommendations.
Both recommendation sections follow the main product section in the installed
product templates: related first, then complementary. Their screen position
depends on the product content. They are available only on product templates.
The cart drawer uses a different metafield, custom.complementary; see the
metafield inventory.
Recently viewed (recently-viewed)
A horizontal row of products the customer has recently viewed. Every
product page records the view in the browser, whether or not this section
is installed: the most recent ~10 product handles are kept in
localStorage (no expiry; entries persist until evicted by the 10-item cap
or cleared by the browser). The same list fills the recently viewed rows on
the 404 page and on searches with no results. Renders nothing if the customer
has no recent products. This section is available only on product templates
and is not pre-installed in the supplied product layouts; add it if you want
this row.
| Setting | Type | Options and notes |
|---|---|---|
Heading (heading) | text | — |
Products shown (limit) | range | 2–8; step 1. Default: 4. |
Custom Liquid section
Custom Liquid (custom-liquid)
Free-form Liquid / HTML / inline style block. Use for embedding
analytics scripts, third-party widgets, custom inline content, or
editorial paragraphs that don’t fit any other section. Duplicate the
theme before adding custom code; see Custom Liquid
for support-scope notes.
| Setting | Type | Options and notes |
|---|---|---|
Liquid code (custom_liquid) | liquid | Merchant-authored Liquid. Renders as-is in the section position. |
See Custom Liquid for examples and patterns.
Chrome sections
The header and footer wrap every page. They’re configured through section groups so merchants can rearrange them, but the individual sections themselves have settings that surface in the Header and Footer entries in the Editor’s left rail.
Header (header)
The site-wide header with logo, main menu, announcement bar above, utility icons, and country / language switcher. Included in the header section group, with a one-instance limit.
| Setting | Type | Options and notes |
|---|---|---|
Sticky on scroll (sticky) | checkbox | Default: on. Header stays at the top while scrolling. Auto-hides on scroll-down, returns on scroll-up. |
Logo position (logo_position) | select | Left / Center. Default: Center. With Left, the menu can appear inline from 1024 px; with Center, from 1200 px, using only the space to the left of the logo. |
Transparent over hero on home page (transparent_on_home) | checkbox | Default: off. Overlays the header on the first section of the home page. The header turns solid once you scroll past it. |
Text and icon color over hero (transparent_text) | select | Light (for dark heroes) / Dark (for light heroes). Default: Light (for dark heroes). The theme can’t detect your hero image’s brightness — pick the option that contrasts your hero for readable, accessible text. |
Mega-menu columns (mega_columns) | select | 2 columns / 3 columns / 4 columns. Default: 3 columns. Number of promo columns shown inside enriched desktop dropdowns. |
Main menu (menu) | link_list | Shown inline on desktop when every top-level link fits on one line beside the logo and header icons. Otherwise, and always on phones and tablets, the menu button opens the menu drawer: this menu followed by your footer menu. |
Show announcement bar (show_announcement) | checkbox | Default: off. |
Announcement text (announcement_text) | text | — |
Allow visitors to dismiss (allow_dismiss) | checkbox | Default: on. |
Show Follow on Shop button (show_follow_on_shop) | checkbox | Default: on. Renders only when the merchant has Shop App / Shop Pay configured. Empty otherwise. |
The header also automatically renders:
- Logo — set in Theme settings → Brand.
- Mega-menu columns — selects 2, 3, or 4 columns for enriched dropdowns. Add a Mega image block to include an image.
- Mega-menu enrichment blocks — add Header blocks of type
Mega image, Mega collection, Mega product, or Mega promo.
Each block has Parent menu item URL (
parent_link_url); paste the URL of a top-level menu link that has child links to attach that block to the link’s desktop dropdown. Your store’s domain, letter case, and a trailing slash don’t matter; leave out any language prefix such as/fr, and include a?queryonly if the menu link has the same one. For label-only parents, give each its own fragment link, such as#women(not case-sensitive), and paste that; if several parents link to#, blocks attach to the first only. When a parent link has matching mega blocks, the dropdown widens to the configured mega-column layout. Mega blocks don’t appear in the menu drawer. - Account icon — uses Shopify’s
<shopify-account>web component on mobile and desktop. Hidden when customer accounts are not enabled. The account menu handle is fixed (customer-account-main-menu) and is not exposed as a setting. - Cart icon — links to cart drawer or
/cartdepending on Theme settings → Cart → Cart style. - Search icon — opens the predictive search overlay when enabled in Theme settings → Search; otherwise links to the search page.
Blocks:
- Mega image (
mega_image) —parent_link_url, image, heading, body, Button label, Button link. - Mega collection (
mega_collection) —parent_link_url, collection, heading override, product limit (3–12). - Mega product (
mega_product) —parent_link_url, product, heading override. - Mega promo (
mega_promo) —parent_link_url, heading, body, badge, Button label, Button link.
Promo popup (promo-popup)
Global promo overlay rendered from layout/theme.liquid via the
promo-popup snippet. It is not an addable section; merchants
configure it under Theme settings → Promo popup. It is skipped
on cart, gift card, customer-account surfaces, and gift-card PDPs.
| Setting | Type | Options and notes |
|---|---|---|
Enable promo popup (promo_popup_enabled) | checkbox | Default: off. Turn on only for an active campaign. |
Heading (promo_popup_heading) | text | Default: “Subscriber updates”. |
Body (promo_popup_body) | richtext | — |
Image (promo_popup_image) | image_picker | — |
Popup content (promo_popup_content_mode) | select | Call to action / Newsletter signup / Newsletter signup and call to action. Default: Newsletter signup. |
Button label (promo_popup_button_label) | text | Default: “Read more”. Used when the popup includes a call to action. |
Button link (promo_popup_button_link) | url | — |
Newsletter tag (promo_popup_newsletter_tag) | text | Comma-separated tags added to the customer record. Default: newsletter,promo-popup. |
Email label (promo_popup_email_label) | text | — |
Email placeholder (promo_popup_email_placeholder) | text | — |
Submit button label (promo_popup_submit_label) | text | — |
Success message (promo_popup_success_message) | text | — |
Error message (promo_popup_error_message) | text | — |
Require marketing consent checkbox (promo_popup_require_consent) | checkbox | Default: off. Customers must tick the box before subscribing. |
Consent text (promo_popup_consent_text) | text | Plain text only; shown next to the consent checkbox. |
Delay before showing (promo_popup_delay_seconds) | range | 0–30 s; step 1. Default: 6. |
Display frequency (promo_popup_frequency) | select | Every visit / Once per session / Once per N days / Once ever. Default: Once per N days. |
Days between displays (promo_popup_frequency_days) | range | 1–100 d; step 1. Default: 7. Used with Once per N days. |
Display reset key (promo_popup_storage_key) | text | Default: default. Change the value to show the popup again to visitors who dismissed it. |
New installations start with a 3-second delay, Once per session, and the
reset key subscriber-updates.
After a visitor subscribes — in the popup or, when the popup offers newsletter signup, through the footer or a Newsletter section — the popup stops appearing in that browser at every frequency until you change Display reset key. Clicking its button or any link in it counts as a dismissal. If the visitor is typing in a field when the delay ends, or adds a product to the cart, the popup skips that page without counting a dismissal. The Theme Editor preview ignores these records.
Footer (footer)
The site-wide footer with link columns, optional newsletter signup, optional markets switcher, optional payment icons, and the copyright / powered-by line. Included in the footer section group, with a one-instance limit.
| Setting | Type | Options and notes |
|---|---|---|
Show newsletter signup (show_newsletter) | checkbox | Default: on. |
Newsletter heading (newsletter_heading) | text | — |
Newsletter body (newsletter_body) | richtext | — |
Also show country / language switcher in footer (show_markets_in_footer) | checkbox | Default: off. Honored only when a header switcher (dropdown / modal) is active. Footer-only mode renders here regardless. Off by default — design recommends one switcher per theme. |
Copyright extra (copyright_extra) | text | — |
Blocks:
- Link column (
link_list) — heading + menu picker. Up to 4 columns; each can point at a different menu handle, but every column defaults to thefooterhandle. - Rich text column (
rich_text) — heading + body for free-form copy (e.g. address, store hours). - Payment icons (
payment_icons) — opt-in. Renders the icons for your enabled Shopify payment gateways (usesshop.enabled_payment_types+payment_type_svg_tag, full color). Hides itself when no gateways are enabled. Settings: Show label (default off) + Label text.
The footer also automatically renders:
- Powered-by-Shopify line — verbatim per Theme Store rules.
- Social media icons — from Theme settings → Social media URL
fields. Hides any icon whose URL is empty or does not begin with a
valid
http://orhttps://scheme.
Theme-level Footer settings (in Theme settings → Footer, not the Footer section’s per-instance settings):
- Show back-to-top button — when enabled, a back-to-top button appears on every page except product pages (where the sticky add-to-cart bar occupies the same screen real estate). Below 1024 px it is also hidden on the cart page, where Checkout uses that corner.
Footer link columns become interactive accordions below 768 px and start open. This responsive behavior has no separate setting.
Mobile bottom navigation (mobile-bottom-nav)
A bottom navigation bar on phones (≤ 767.98 px) that is hidden at the top of the page and slides in once the header scrolls away (it stays shown on pages too short to scroll past the header). Hidden on tablet and desktop (768 px and up).
It holds up to 5 Tab blocks: each block is one tab (icon + label + link). There are no section-level settings. The cart tab uses a special “cart-count” badge that updates live.
This section can only live in the footer section group (its schema
is enabled_on the footer group only) — it cannot be added to
individual template JSON files. It already ships inside
footer-group.json and is managed there.
Template-specific sections
These main-* sections drive each template. You don’t add them as
general-purpose sections; they supply the main content within each template
JSON. They expose customization for the page they render.
| Section | Drives |
|---|---|
main-product | templates/product.json |
main-collection | templates/collection.json |
main-list-collections | templates/list-collections.json |
main-cart | templates/cart.json |
main-search | templates/search.json |
main-blog | templates/blog.json |
main-article | templates/article.json |
main-page | templates/page.json |
main-page-contact | templates/page.contact.json |
main-password | templates/password.json |
main-404 | templates/404.json |
Each main-* section has the settings appropriate to its page —
e.g. main-product exposes Layout, Low-stock threshold, free-shipping progress,
sticky add-to-cart, and detail-block behavior. Variant controls are product
blocks and shared theme settings, not a section-level “variant picker style”.
Product section (main-product) settings:
| Setting | Type | Options and notes |
|---|---|---|
Layout (layout) | select | Stacked — gallery + info / Split — sticky info column / Gallery-first — editorial mosaic. Default: Stacked — gallery + info. Mobile collapses to a single column regardless of layout choice. |
Low-stock threshold (low_stock_threshold) | range | 0–20; step 1. Default: 5. 0 = off. Honest “Only N left” pill when stock is at or below this number. Only renders when inventory tracking is enabled and ‘continue selling when out of stock’ is off. |
Show free-shipping progress (show_freeship_progress) | checkbox | Default: off. Reads the threshold from theme settings → Cart. |
Show sticky add-to-cart bar (show_sticky_cta) | checkbox | Default: on. Slides up after the buy box scrolls out of view. |
Description open by default (description_open) | checkbox | Default: off. |
Detail blocks display mode (details_display_mode) | select | Accordion / Tabs on desktop, accordion on mobile. Default: Accordion. Controls Description, Materials and care, and other accordion blocks. Mobile always uses the accordion. |
Collection and search filters auto-render visual swatches when Shopify
reports filter.presentation == 'swatch' or
filter.presentation == 'image'. Configure those swatches in Shopify
admin’s Color swatch settings; values without a swatch fall back to
the text filter row.
Internal rendering endpoints
These sections are storefront implementation endpoints, not addable content sections or alternate product layouts:
| Section | Used by |
|---|---|
product-card-only | product.card.json (layout: false), fetched by Recently viewed to render a card. The reusable card itself is snippets/product-card.liquid. |
product-card-state | product.card-state.json (layout: false), for product-card state updates. |
product-quantity-rule | product.quantity-rule.json (layout: false), for product quantity-rule updates. |
product-quick-view | product.quick-view.json (layout: false), for the quick-view modal. |
cart-drawer-crosssell | Cart drawer cross-sell refresh through Shopify’s Section Rendering API. |
Do not assign the four internal product templates to products as their storefront template. Use the normal product template for a complete product page.
Product, collection and shop metafields
These fields are optional. The theme reads existing values; it does not require them for a basic store launch. Create appropriate definitions and populate the resources where you want the feature to appear. Text fields below are rendered as text, not arbitrary HTML.
| Resource | Namespace and key | Value | Used for |
|---|---|---|---|
| Product | custom.badge | Single-line text or list of single-line text | Custom badge labels on eligible product cards and product pages when custom badges are enabled. Combined with badge-prefixed tags, deduplicated, with up to three custom labels. |
| Product | custom.preorder_ships_on | Text/date value displayed as a shipping label | Shipping information beside the pre-order button, when pre-orders are enabled and a tracked, available variant permits continuing to sell at zero or negative stock. |
| Product | custom.pairs_with | List of product references | Curated products for a Related products section set to Complementary. An absent/empty list falls back to Shopify recommendations. |
| Product | custom.complementary | List of product references | Cart drawer cross-sell for the first cart line’s product, up to four products. This is a separate field from custom.pairs_with; the current cart code has no recommendations fallback when it is empty. |
| Product | custom.story_article | Article reference | The product page’s Editorial story block when its automatic metafield source is enabled. Without a value that block renders no story; turn off the automatic source to use its article picker. |
| Product | custom.materials | Text, including multiple lines | Materials content in the Materials and care product block. |
| Product | custom.care | Text, including multiple lines | Care content in the same block. |
| Product | custom.origin | Single-line text | Origin content in the same block. When all three fields are empty, the block can use its configured fallback body. |
| Product | reviews.rating | Rating | Rating summary and eligible product structured data, together with a valid rating count. Usually supplied by a review app. |
| Product | reviews.rating_count | Integer | Review count accompanying the rating. |
| Collection | custom.hero_image | File reference containing an image | Collection banner image, before the collection image and first product image fallbacks. |
| Shop | mercer.search_chips | Comma-separated text | Suggested search terms in predictive search. Empty entries are ignored; absent content uses translated defaults. |
| Shop | global.twitter_account | Single-line text | Optional Twitter/X handle, output as the twitter:site tag on pages using the main theme layout and on the password page. |
B2B surfaces also read company-location metafields. These mirror or label native B2B configuration; they do not replace Shopify’s payment terms. See B2B for setup and eligibility.
| Resource | Namespace and key | Value | Used for |
|---|---|---|---|
| Company location | mercer_b2b.payment_terms_label | Single-line text | Payment-terms label in the company switcher, tier table, and cart summary. |
| Company location | mercer_b2b.payment_terms_due_in_days | Integer | NET payment-term days shown in the B2B cart summary. |
| Company location | mercer_b2b.purchase_orders_required | Boolean | Purchase-order policy indication and required PO input on B2B cart surfaces. |
What’s next
- Use Custom Liquid for sections this reference doesn’t cover.
- Use Markets for currency / language switchers (the switcher style is set in Theme settings → Markets; the dropdown / modal then render in the header).
- Use B2B for company/location switching, tier pricing, quantity rules, and quick order.