InstantSearch

Algolia Search and Discovery includes a search results page powered by InstantSearch. It replaces your default Shopify search results page and comes with several InstantSearch widgets.

The InstantSearch results page offers a rich user experience, but the implementation can be more involved than an autocomplete menu. It’s best if you work together with a frontend developer to integrate the InstantSearch results page into your shop.

Configuration

To configure the InstantSearch page, go to the Search options tab in your Shopify app.

For the CSS Selector option, the default value aims to target the main element of your search results page. If it isn’t the case, you can enter the value that matches your theme, or you can add the class algolia-shopify-instantsearch to the DOM element you want to use.

Templates

If you want to configure the InstantSearch page and go beyond the configuration options, you can edit the templates directly. The InstantSearch widgets render the results into HTML using the html tagged template. For more information, see Templating your UI.

Main template files

The main template files are:

• assets/algolia_instant_search.js.liquid
• snippet/algolia_instant_search.css.liquid
• snippet/algolia_instant_search.liquid

assets/algolia_instant_search.js.liquid

The main file of the InstantSearch page: it contains most of the frontend logic. It defines all InstantSearch widgets that are needed for the search.

snippet/algolia_instant_search.css.liquid

This file contains all the styling for the InstantSearch page. If you want to change the look of the InstantSearch menu, edit this file. Configuration options are passed from the assets/algolia_instant_search.js.liquid file to the style sheet. For example:

1
2
3
4
5
6
7
8
{
  // Theme colors (configurable in your app)
  colors: {
    main,
    secondary,
    highlight,
  }
}

snippet/algolia_instant_search.liquid

This template handles the page layout. For example:

1
2
3
4
{
  facets,
  multipleSortOrders    // Boolean value indicating number of sort orders
}

Search header templates

The search header is the small area between the search box and the results. The search header template files are:

• assets/algolia_sort_orders.js.liquid. Prepares and formats the sort orders expected by InstantSearch’s sortBy widget.
• snippet/algolia_instant_search_stats.liquid. This template is used with the stats widget. The text function customizes the text.

Filtering templates

The filtering template files are:

• assets/algolia_facets.js.liquid. Prepares and formats the facets expected by InstantSearch’s faceting widgets.
• snippet/algolia_instant_search_facet_item.liquid. This template represents each line of a refinementList widget. The item function customizes the template UI.

Results templates

The results template files are:

• snippet/algolia_instant_search_product.liquid. This template handles product entries. It receives the Algolia response record. The item function customizes the template UI.
• snippet/algolia_instant_search_no_result.liquid. This template handles a search with no results. The empty function customizes the template UI.

Template files with Hogan.js

The old version of the InstantSearch widget uses Hogan.js as a templating engine. For more information, see Templating languages.

To change the behavior of the search page, edit the following Hogan.js template files.

Main template files

The main template files are:

• assets/algolia_instant_search.js.liquid. Prepares and formats the facets expected by InstantSearch’s faceting widgets.
• snippet/algolia_instant_search.css.hogan.liquid
• snippet/algolia_instant_search.hogan.liquid

snippet/algolia_instant_search.css.hogan.liquid

This file contains the styling for the InstantSearch page. If you want to change the look of the InstantSearch menu, edit this file. The file is a .hogan template to allow configuration options to be passed from the JavaScript file to the style sheet. For example:

1
2
3
4
5
6
7
8
9
{
  // Theme colors (configurable in your app)
  colors: {
    main,
    secondary,
    highlight,
  },
  helpers
}

snippet/algolia_instant_search.hogan.liquid

This template handles the page layout. For example:

1
2
3
4
5
{
  facets,
  helpers,
  storeName
}

Search header templates

The search header is the small area between the search box and the results. The search header template files are:

• assets/algolia_sort_orders.js.liquid. Prepares and formats the sort orders expected by InstantSearch’s sortBy widget.
• snippet/algolia_instant_search_stats.hogan.liquid

snippet/algolia_instant_search_stats.hogan.liquid

This template is used with the stats widget. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  cssClasses,       // CSS classes used with the stats widget
  hasNoResults,
  hasOneResult,
  hasManyResults,
  helpers,
  hitsPerPage,      // Number of results per page
  nbHits,           // Total number of results
  nbPages,          // Total number of pages
  page,             // Current page
  processingTimeMS,
  processingTimeS,
  query,            // Current query
  start,            // Position of the first result of the page
  end               // Position of the last result of the page
}

Filtering templates

The filtering template files are:

• assets/algolia_facets.js.liquid. Prepares and formats the facets expected by InstantSearch’s faceting widgets.
• snippet/algolia_instant_search_facet_item.hogan.liquid
• snippet/algolia_instant_search_current_refined_values_item.hogan.liquid

snippet/algolia_instant_search_facet_item.hogan.liquid

This template represents each line of a refinementList widget. For example:

1
2
3
4
5
6
7
8
9
10
11
12
{
  count,                  // Number of results matching this facet
  cssClasses,             // CSS classes used with the widget
  helpers,
  isExcluded,             // Is this facet excluded? (not used in our front end, allows to exclude search results)
  isRefined,              // Is this facet used?
  name,                   // Facet value
  type: {                 // Convenience object to use within the template like so `[[# type.conjunctive ]]Only if the facet is conjunctive[[/ type.conjunctive ]]`
    <TYPE_NAME>: true
  }
  url                     // Search URL after the usage of the facet
}

snippet/algolia_instant_search_current_refined_values_item.hogan.liquid

This template represents each line of a currentRefinements widget. For example:

1
2
3
4
5
6
7
8
9
10
{
  attributeName,        // Facet attribute
  count,                // Amount of results matching this facet
  cssClasses,           // CSS classes used by the widget
  exhaustive,           // Is the count exhaustive
  helpers,
  label,                // Facet name (title used in the facet header)
  name,                 // Facet value
  type                  // Type of facet: one of ['facet', 'exclude', 'disjunctive', 'hierarchical', 'numeric', 'tag']
}

Results templates

The results template files are:

• snippet/algolia_instant_search_product.hogan.liquid
• snippet/algolia_instant_search_no_result.hogan.liquid

snippet/algolia_instant_search_product.hogan.liquid

This template handles product entries. It receives the Algolia response record. For example:

1
2
3
4
5
6
7
8
9
{
  // Product attributes
  can_order,         // Can be added to cart
  helpers,

  // Algolia search result attributes: https://algolia/doc/api-client/php/search#sample
  _highlightResult,  // For all attributes in the attributesToHighlight
  _snippetResult     // For all attributes in the attributesToSnippet setting of the index
}

snippet/algolia_instant_search_no_result.hogan.liquid

This template handles a search with no results. For example:

1
2
3
4
{
  helpers,
  query         // Query used for the search
}