Predictive search
You can add predictive search to your theme so that suggested results appear immediately as you type into the search field. Predictive search helps customers articulate and refine their search queries, and provides new ways for them to explore an online store. It also lets them quickly browse matches without having to leave their current page to see a separate list of search results.
Predictive search supports suggestions for products, collections, pages, and articles.
To add predictive search to your theme, you need to use the Ajax Predictive Search API. And because predictive search affects the appearance of your online store, it’s important to be familiar with the UI requirements and best practices before you implement it.
How suggestions are generated
The predictive search dropdown displays the following information when you enter a query.
| Point | Description |
|---|---|
| 1 | Predictive search dropdown |
| 2 | Product suggestions |
| 3 | Collection suggestions |
| 4 | Page suggestions |
| 5 | Article suggestions |
After you start typing into the search bar, predictive search suggests results that are related to what you’re typing. They match search terms either exactly or with typo tolerance on searchable properties of shop resources.
Matching products or variants are returned as product suggestions that drop down from the search bar. For example, you’re looking for a snowboard and type very-fast snowbo. Product suggestions appear for products or variants that contain very, fast, and a term that begins with snowbo.
If a word is separated by a hyphen or space, then it will be considered as two terms. Words or phrases that are separated into multiple terms return different results than a single term that includes the same words. For example, T-shirt and t shirt return the same results, but tshirt does not.
Product variants are returned only when the query matches terms specific to the variant title. Only the variants with the most matching terms are returned as results. For example, a store has a snowboard with a blue variant and a light blue variant. If you search for snowbo, then Snowboard product will be returned. However, if you search for light blue snowbo, then only the light blue variant is returned.
UI requirements and best practices
Before you implement predictive search, make sure that you’re familiar with the following UI requirements and best practices. These include guidance for displaying products, styling the search field, and creating a search experience that is both accessible and mobile friendly.
| UI requirements | |
|---|---|
| Number of resources shown |
The predictive search API returns a maximum of 10 results per resource type. For example, for a query that matches on both products and pages, the API returns a maximum of 10 matching product resources and 10 matching page resources. However, if the query returns matches for multiple resource types, then consider tailoring responses to include a mix of resources. Limit the overall number of suggestions to avoid overwhelming the user or taking up too much space on the screen. Also, you can adjust the number of suggestions to display depending on the context where they appear. |
| Close action |
Include a close button. It should be in the form of an icon or text that leaves the search experience and closes the product suggestion dropdown. This action should not clear the query. |
| Search action |
Include a search button. It should be in the form of an icon or text that takes the user to the search results page. Also achieved by clicking enter on a keyboard, or “go”/”search” on a mobile keyboard. |
| Clearing query |
The query should stay in the search field until the customer explicitly clears the query or navigates to a different page. The used query should be repeated on the search result page. |
| Empty state |
Hide the empty-state drop-down when there are no product suggestions that match the query. The lack of feedback from predictive search should encourage customers to continue their search from the results page. |
| Mobile interactions |
Focus the search field when tapping on the search icon. Reduce the number of interactions required to use search. If a user taps the search icon, then focus the search field and ensure that they are able to begin searching immediately. Allow scrolling within the drop-down. When displaying product suggestions, make sure that the user is able to scroll through the results. |
| Accessibility requirements | |
|---|---|
| Browser and mobile autocomplete |
Disable browser-based autocomplete and search history, and mobile OS text autocorrect and autocomplete.
|
| Best practices | |
|---|---|
| Resource information |
Expose only the information essential to the customer’s search. To maintain a streamlined and consistent experience, reduce search interface content and resource data to the minimum amount necessary to make selection meaningful. Using the API, you can control which elements are exposed or hidden. Although you can adapt this to the needs of the merchant, you should consider only exposing these recommended fields: Product fields
|
| Labels |
Don’t show a "Sold out" label for suggested product variants in case the user is looking for a variant that isn’t sold out. "Sold out” should be shown only when the product object within the response has its Use a heading to label product suggestions to help users anticipate the type of results they can expect. For example, use a "Products" heading for product suggestions. |
| Actions |
Include a clear button. Clear button or text in the search field to delete any query entered. |
| Search visibility |
Display the search field, or at least the search icon, in the header of all pages. If search is a significant element of the overall experience you want to provide, then make sure that it’s displayed prominently. For stores with only one product or a small number of products, the search field can be located within a hamburger menu. |
| "More results" links |
Display a link in the list of product suggestions to indicate that there might be more results on the search results page. For example, the link could include the text "Search for [your query]" (where [your query] is what the user has entered in the search field) or "View all results." |
Example search patterns
The following layouts and patterns can help you implement predictive search effectively in your theme.
Inline search drop down
Desktop: inline search
The search dropdown overlays the page, without taking up too much visual space.
The search bar is visible on the site.
Predictive search appears as a dropdown under the search field.
Mobile: inline search
In-menu search
Desktop: in-menu search
The search dropdown overlays the page, without taking up too much visual space.
No search bar is visible on the site.
Search appears in the menu.
Predictive search results appear under the search field in the menu.
Alternatively, the search field can be positioned at the top of the menu. In this case, product suggestions would overlay the menu list (see the in-menu mobile example for this layout).
Mobile: in-menu search
Requesting predictive search results from the Ajax API
You can access predictive search results by making requests to the /search/suggest.json? endpoint in the Shopify Ajax API. The API responds with JSON, and doesn't require custom Liquid.
To learn how this endpoint works, see the Predictive Search API.
Example using Predictive Search Library
To help implement Predictive Search in your theme, you may want to use the Predictive Search Library which part of the Shopify/theme-scripts GitHub repository.
import PredictiveSearch from "@shopify/theme-predictive-search";
var predictiveSearch = new PredictiveSearch({
resources: {
type: [PredictiveSearch.TYPES.PRODUCT],
limit: 4,
options: {
unavailable_products: PredictiveSearch.UNAVAILABLE_PRODUCTS.LAST,
fields: [
PredictiveSearch.FIELDS.TITLE,
PredictiveSearch.FIELDS.VENDOR,
PredictiveSearch.FIELDS.PRODUCT_TYPE,
PredictiveSearch.FIELDS.VARIANTS_TITLE
]
}
}
});
// Set success event listener
predictiveSearch.on("success", suggestions => {
const productSuggestions = suggestions.resources.results.products;
if (productSuggestions.length > 0) {
var firstProductSuggestion = productSuggestions[0];
alert(`The title of the first product suggestion is: ${
firstProductSuggestion.title}`
)
}
});
// Set error event listener
predictiveSearch.on("error", error => {
console.error("Error message:", error.message);
});
// Send query
predictiveSearch.query("The Calling");Theme settings settings_schema.json
Global settings example:
[
{
"name": "Search",
"settings": [
{
"type": "checkbox",
"id": "predictive_search_enabled",
"label": "Enable product suggestions",
"info": "This will also affect the search field on the search page."
},
{
"type": "checkbox",
"id": "predictive_search_show_vendor",
"label": "Show vendor"
},
{
"type": "checkbox",
"id": "predictive_search_show_price",
"label": "Show price"
}
]
}
]