Shopify Template Customization Guide

For Merchants and Theme Developers

This guide explains how to safely customize the Marqo search widget's appearance using the Advanced Template Editor and Custom CSS.

How Styling Works

Your search widget's appearance is controlled by three layers:

1. Admin Controls — Color pickers, sliders, and toggles in the settings UI. These set CSS variables automatically.
2. Template CSS — The structural styling (layout, spacing, transitions). Editable in the Advanced editor.
3. Custom CSS — Your override layer. Anything you put here takes priority.

The admin controls set CSS variables like --marqo-sale-badge-bg: #dc2626. The template CSS references them with var(--marqo-sale-badge-bg). This means you can freely edit the template HTML and CSS without breaking the admin controls — as long as you keep the var() references.

Safe Editing Rules

DO

• Change layout properties (padding, margin, position, flex, grid)
• Change transitions and animations
• Add new CSS classes and elements
• Rearrange HTML elements within a template
• Use var(--marqo-*) references for colors and sizes you want admin-controllable

DON'T

• Replace var(--marqo-*) with hardcoded colors (the admin control will stop working)
• Remove HTML elements with marqo- class names (the admin will warn you if you do)
• Remove data-position or data-align attributes (used by the styling system)

If You Break Something

Each template has a Reset to Default button that restores the original HTML and CSS while keeping all your color and size settings from the admin controls.

Available CSS Variables

All variables are scoped to .marqo-search-layout. Use them in your Custom CSS or template edits.

Sale Badge

Variable	Description	Default
--marqo-sale-badge-bg	Badge background color	#dc2626
--marqo-sale-badge-text	Badge text color	#ffffff
--marqo-sale-badge-radius	Badge corner rounding	4px

CTA Button

Variable	Description	Default
--marqo-cta-bg	Button background color	#000000
--marqo-cta-text	Button text color	#ffffff
--marqo-cta-border-color	Button border color	#000000
--marqo-cta-border-width	Button border thickness	0px
--marqo-cta-border-radius	Button corner rounding	0px
--marqo-cta-width	Button width (100% or auto)	100%

Price Display

Variable	Description	Default
--marqo-price-sale-color	Sale price text color	#dc2626
--marqo-price-compare-color	Compare-at (strikethrough) price color	#9ca3af
--marqo-price-regular-color	Regular price text color	#059669
--marqo-price-font	Price font family	inherit
--marqo-price-size	Price font size	16px
--marqo-price-weight	Price font weight	700

Product Card

Variable	Description	Default
--marqo-card-bg	Card background color	#ffffff
--marqo-card-border-color	Card border color	#e2e8f0
--marqo-card-border-width	Card border thickness	1px
--marqo-card-border-radius	Card corner rounding	8px
--marqo-column-spacing	Gap between cards in the grid	16px
--marqo-card-image-ratio	Image aspect ratio (1/1, 3/4, 9/16)	1/1

Vendor Name

Variable	Description	Default
--marqo-vendor-font	Vendor text font family	inherit
--marqo-vendor-size	Vendor text font size	12px
--marqo-vendor-weight	Vendor text font weight	500
--marqo-vendor-color	Vendor text color	#64748b

Product Title

Variable	Description	Default
--marqo-title-font	Title font family	inherit
--marqo-title-size	Title font size	14px
--marqo-title-weight	Title font weight	600
--marqo-title-color	Title text color	#1e293b

Reviews

Variable	Description	Default
--marqo-star-color	Star rating fill color	#f59e0b
--marqo-star-size	Star rating font size	16px
--marqo-review-text-color	Review count text color	#6b7280

Filter Sidebar

Variable	Description	Default
--marqo-filter-bg	Sidebar background color	#ffffff
--marqo-filter-radius	Sidebar corner rounding	8px
--marqo-filter-text-color	Filter label text color	#1e293b
--marqo-filter-text-size	Filter label font size	14px
--marqo-filter-text-font	Filter label font family	inherit
--marqo-filter-text-weight	Filter label font weight	500
--marqo-filter-separator	Divider line color (transparent to hide)	#e2e8f0
--marqo-filter-active-indicator	Active filter indicator color (transparent to hide)	#3b82f6
--marqo-filter-btn-bg	Filters button background	#ffffff
--marqo-filter-btn-text	Filters button text color	#1e293b
--marqo-filter-btn-border	Filters button border color	#e2e8f0

Sort Dropdown

Variable	Description	Default
--marqo-sort-dropdown-bg	Sort dropdown background	#ffffff
--marqo-sort-dropdown-border	Sort dropdown border color	#e2e8f0
--marqo-sort-dropdown-text	Sort dropdown text color	#1e293b

Per-Page Dropdown

Variable	Description	Default
--marqo-page-dropdown-bg	Per-page dropdown background	#ffffff
--marqo-page-dropdown-border	Per-page dropdown border color	#e2e8f0
--marqo-page-dropdown-text	Per-page dropdown text color	#1e293b

Results Count

Variable	Description	Default
--marqo-results-font	Results count font family	inherit
--marqo-results-size	Results count font size	14px
--marqo-results-weight	Results count font weight	400
--marqo-results-color	Results count text color	#6b7280

Custom CSS Examples

Change card hover effect

.marqo-product-card:hover {
  transform: scale(1.02);
  box-shadow: 0 20px 40px rgba(0, 0, 0, 0.15);
}

Round product images

.marqo-product-card-image {
  border-radius: 50%;
  overflow: hidden;
}

Hide the vendor name

.marqo-vendor { display: none; }

Custom sale badge style

.marqo-sale-badge {
  background: var(--marqo-sale-badge-bg) !important;
  border-radius: 0 !important;
  text-transform: lowercase !important;
  font-style: italic;
}

Full-width cards on mobile

@media (max-width: 480px) {
  .marqo-results-grid {
    grid-template-columns: 1fr !important;
  }
}

Change filter sidebar width

.marqo-filter-sidebar {
  width: 280px !important;
  max-width: 280px !important;
}

Use a variable in Custom CSS to override the admin

/* Override the sale badge color just for this page */
.marqo-search-layout {
  --marqo-sale-badge-bg: hotpink;
  --marqo-sale-badge-text: black;
}

Responsive Behavior

The widget automatically scales down on smaller screens:

Screen size	What changes
Desktop (>1024px)	Full layout — sidebar filters, multi-column grid
Tablet (481–1024px)	Reduced columns, 90% font sizes, 75% spacing
Mobile (≤480px)	Single/dual column, 80% font sizes, 50% spacing

The column counts at each breakpoint are set in the admin UI under Product Column Breakpoints. The filter sidebar switches to a mobile overlay at the Filter Mobile Breakpoint (configurable, default 768px).

Font and spacing scaling is proportional — if you increase the base vendor font size to 16px in the admin, it automatically becomes 14.4px on tablet and 12.8px on mobile.

Handlebars Variables

The product card HTML template uses Handlebars for dynamic content. Available variables:

Product Data

Variable	Description
{{productUrl}}	Link to the product page
{{imageUrl}}	Primary product image URL
{{title}}	Product title
{{vendor}}	Brand/vendor name
{{price}}	Formatted price (e.g., "$40.00")
{{compareAtPrice}}	Formatted compare-at price (empty if not on sale)
{{variantTitle}}	Variant name
{{description}}	Truncated product description
{{productCollections}}	Collection names

Sale Badge

Variable	Description
{{salePercent}}	Sale discount percentage (0 if not on sale)
{{saleBadgeLabel}}	Formatted badge text (e.g., "SAVE 40%")
{{saleBadgePosition}}	Badge position ("top-left" or "top-right")

Reviews

Variable	Description
{{reviewAverage}}	Average review rating (0 if no reviews)
{{reviewCount}}	Number of reviews
{{reviewPercentage}}	Star fill percentage (0-100)
{{showReviewCount}}	Whether to show the review count number

CTA Button

Variable	Description
{{ctaEnabled}}	Whether the CTA button is shown
{{ctaButtonText}}	Button text (e.g., "Shop Now")

Image Carousel

Variable	Description
{{hasMultipleImages}}	Whether product has multiple images
{{{imageUrlsJson}}}	JSON array of all image URLs (triple braces = unescaped)
{{carouselAlwaysClass}}	CSS class for always-visible arrows

Conditionals

{{#if salePercent}}
  <!-- Only shown for products on sale -->
{{/if}}

{{#if compareAtPrice}}
  <!-- Only shown when there's a compare-at price -->
{{/if}}

{{#if reviewAverage}}
  <!-- Only shown for products with reviews -->
{{/if}}

{{#if ctaEnabled}}
  <!-- Only shown when CTA button is enabled -->
{{/if}}

{{#if hasMultipleImages}}
  <!-- Only shown for multi-image products -->
{{/if}}

Dynamic Product Fields

Any field from the Marqo index can be used directly:

{{productType}}
{{productTags}}
{{variantOption1}}
{{variantOption2}}

Troubleshooting

"Missing elements" warning in Advanced editor

You removed an HTML element that admin controls depend on. The warning tells you which controls are affected. Use the Reset button to restore the element.

Admin color picker has no effect

The template CSS might have a hardcoded color instead of a var() reference. Check the Advanced CSS editor for the selector and replace the hardcoded value with the appropriate var(--marqo-*).

Custom CSS not applying

Make sure your selector is specific enough. Use !important if needed, or increase specificity:

/* More specific */
.marqo-search-layout .marqo-product-card .marqo-vendor {
  color: red;
}

Changes not showing after save

1. Hard refresh the storefront (Cmd+Shift+R)
2. Clear sessionStorage: run sessionStorage.clear() in the browser console
3. Wait 1-2 minutes for Shopify's metafield cache to update