Skip to main content
The Predictive Search section powers the search autocomplete dropdown that appears when customers type in the header search bar. It provides instant, real-time suggestions without requiring a page reload, improving product discovery and reducing search friction.

​
What this section controls

This section controls search autocomplete with the following capabilities:
  • Real-time AJAX-powered search suggestions
  • Multiple content type results (queries, products, pages, articles, collections)
  • Instant results display without page reload
  • Smart result limits for relevant suggestions
  • Minimum character trigger (typically 2 characters)
  • Keyboard navigation support
  • Debounced API calls for performance
  • No Theme Customizer settings (controlled by Shopify API)
This is a dynamic AJAX-powered component with no theme customizer settings. All functionality is controlled by Shopify’s Predictive Search API and the theme’s JavaScript code.

​
Key Features

Instant Results

Real-time suggestions appear as customers type

Multiple Content Types

Shows queries, products, pages, articles, and collections

Smart Limits

Displays most relevant results without overwhelming users

No Page Reload

AJAX-powered for seamless, fast search experience

​
How It Works

Trigger Conditions:
  • Customer types in header search input field
  • Typically requires minimum 2 characters
  • Updates automatically as typing continues
  • Debounced to prevent excessive API calls
Display Behavior:
  • Appears as dropdown below search input
  • Organized layout with clear section headings
  • Responsive design (adapts to mobile/desktop)
  • Smooth show/hide animations
User Interactions:
  • Click any result to navigate directly
  • Bottom button shows full search page
  • Escape key or clicking outside closes dropdown
  • Keyboard navigation supported (arrow keys, enter)
The component searches across multiple content types and displays results in priority order:Queries (Limit: 3)
  • Popular search terms matching the input
  • Highlighted matching text (styled)
  • Links to full search results for that term
  • Example: Customer types “red” → suggests “red shoes”, “red dress”
Collections (Limit: 3)
  • Collections matching search term
  • Collection title displayed
  • Links directly to collection page
Pages (Limit: 3)
  • Informational pages (About, FAQ, etc.)
  • Policy pages (Shipping, Returns, etc.)
  • Custom content pages
Articles (Limit: 3)
  • Blog posts matching search term
  • Article titles displayed
  • Links to full article
Products (Limit: 6)
  • Full product cards with images
  • Product title and price
  • Uses theme’s standard product card component
  • Respects card product layout settings
  • Hidden actions (no quick add or cart buttons)
Total results displayed: Up to 18 items (3 queries + 3 collections + 3 pages + 3 articles + 6 products). This prevents overwhelming users while providing comprehensive results.
Results are organized into clearly labeled sections:Queries Section
  • Heading: “Suggestions” (translatable)
  • List of suggested search terms
  • Highlighted matching text
  • Links to search results pages
Pages & Articles Section
  • Heading: “Pages” (translatable)
  • Combined list of pages and articles
  • Title links only (no thumbnails)
Products Section
  • Heading: “Products” (translatable)
  • Grid layout for product cards
  • Column gap uses theme’s spacing settings
  • 2-3 columns depending on viewport size
View All Button
  • Text: “Search for [terms]” (translatable)
  • Always appears at bottom when results exist
  • Submits search form to show full results page
When no results are found for the search query:Display:
  • Message: “No results for [search term]” (translatable)
  • Checks all resource types before showing empty state
  • No “View all” button displayed
Conditions for Empty State:
  • No products found
  • No pages found
  • No articles found
  • No collections found
  • No query suggestions available
The empty state only appears when all resource types return zero results. If even one result exists in any category, that section will display.

​
Technical Details

API Integration:
  • Uses Shopify’s Predictive Search API
  • Sends search query asynchronously
  • Returns JSON response with results
  • Renders HTML dynamically via Liquid template
Performance Optimization:
  • Debounced input (reduces API calls while typing)
  • Only queries after minimum character count
  • Cancels previous requests if new search starts
  • Lightweight HTML response for fast rendering
JavaScript Requirements:
  • Customers must have JavaScript enabled
  • Component will not function without JS
  • Graceful degradation: regular search still works
The component renders products using the theme’s standard product card snippet:
{%- render 'card-product', 
  product_ref: product, 
  hide_actions: true, 
  class: 'predictive-search__card-product', 
  section_id: section.id, 
  title_small: true, 
  card_index: forloop.index, 
  card_product_layout: settings.card_product_layout 
-%}
Parameters:
  • hide_actions: true - Removes quick add/cart buttons
  • title_small: true - Uses smaller title size
  • card_product_layout - Inherits from theme settings
This ensures visual consistency with product grids throughout the store.
Grid Spacing:
{% style %}
  .predictive-search__grid {
    column-gap: {{ settings.spacing_mobile }}rem;
  }
  @media screen and (min-width: 990px) {
    .predictive-search__grid {
      column-gap: {{ settings.spacing_desktop }}rem;
    }
  }
{% endstyle %}
The product grid respects theme-wide spacing settings for consistency.Custom Classes:
  • .predictive-search__results - Main container
  • .predictive-search__row - Each result section
  • .predictive-search__title - Section headings
  • .predictive-search__links - Query/page/article lists
  • .predictive-search__grid - Product grid container
  • .predictive-search__link - View all button
Searchable Resources:
  • All published products
  • Published collections
  • Published pages
  • Published blog articles
  • Product metafields (if configured)
  • Product variants
Not Searchable:
  • Draft products or pages
  • Password-protected products
  • Products from unpublished sales channels
  • Private collections
  • Customer data
Search Matching:
  • Product titles
  • Product descriptions
  • Product vendor
  • Product tags
  • Collection titles
  • Page titles and content
  • Article titles and content

​
Localization & Translation

All text strings are translatable via theme language files. Key translation keys:
Locale KeyDefault TextUsage
search.queries_titleSuggestionsQueries section heading
search.pages_titlePagesPages & articles heading
search.products_titleProductsProducts section heading
search.empty_with_termsNo results for ""Empty state message
search.search_forSearch for ""View all button text
Edit Translations: Go to Shopify Admin → Online Store → Themes → Actions → Edit Languages

​
Browser Compatibility

JavaScript Required

Component requires JavaScript enabled - falls back to standard search if disabled

Modern Browsers

Supports all modern browsers (Chrome, Firefox, Safari, Edge)

Mobile Responsive

Fully responsive design adapts to all screen sizes

Keyboard Accessible

Supports keyboard navigation (arrow keys, enter, escape)

​
Best practices

Search optimization

Use descriptive, keyword-rich product titles and add comprehensive product descriptions. Tag products with relevant terms customers use when searching. Organize products into logical collections and keep page and article titles clear and searchable for better discovery.

Performance

Optimize product images for fast loading in search results. Keep product titles concise but descriptive. Limit the number of product variants when possible and ensure server response times are fast for instant predictive results.

User experience

Test search with common terms customers actually use. Monitor search analytics to improve product discoverability. Add popular search terms to product tags, keep collection names intuitive, and use clear page titles that match customer intent.

Content quality

Ensure all product titles, descriptions, and tags are complete and accurate. Use consistent terminology across products. Avoid duplicate content and maintain up-to-date information for all searchable content types.

Testing strategy

Regularly test search functionality with various query types. Check that results are relevant and display correctly. Verify mobile search experience and ensure quick result loading times across all devices.

Technical limitations

Understand that result limits, content types, and layout structure cannot be customized via theme settings. Modifications require code changes. Predictive search requires JavaScript and has no fallback autocomplete. Plan accordingly for your store’s needs.

​
Common Questions

Products may not appear if:
  • They are in draft status (not published)
  • They are excluded from specific sales channels
  • They are password-protected
  • Inventory is zero and “Continue selling when out of stock” is disabled
  • They don’t match the search query closely enough
Check product settings and availability in Shopify Admin → Products.
Not via theme settings. The limits are hardcoded:
  • Queries: 3
  • Collections: 3
  • Pages: 3
  • Articles: 3
  • Products: 6
To change these, you must edit the predictive-search.liquid file and modify the limit: parameters in the Liquid code.
Yes, but requires code editing. The section order is determined by the HTML structure in predictive-search.liquid. You can rearrange the {% if %} blocks to change display order.Default order: Queries → Pages/Articles → Products → View All Button
Yes, if metafields are configured as searchable in Shopify admin. Go to Settings → Custom Data → Products and enable “Storefront search” for specific metafields.This allows searching by custom attributes like:
  • SKU numbers
  • Material types
  • Product specifications
  • Custom identifiers
  • Header: Contains the search input that triggers predictive search
  • Main Search: Full search results page for complete search experience
  • Card Product Snippet: Product card component used in search results
  • Shopify Predictive Search API: Backend API powering the search functionality

​
Further Reading

Shopify Search Guide

Learn about Shopify’s search functionality and optimization

Metafields for Search

Configure metafields to expand search capabilities