Quick Start: Shopify

From September 2021, the steps detailed in this page are automated as part of our Klevu Shopify App, but only for new App installations. If you are an existing Klevu App user from before this date, please follow the manual steps in this guide.

This tutorial will guide you through manually adding Klevu Theme to your Shopify store. We will be making some small changes to your Shopify Theme, so please navigate to Shopify Admin Panel > Online Store > Themes, find the theme you wish to edit, then select Actions > Edit Code.


We will be including the Klevu Quick Search Theme on every page, since that will be used to power the quick search bar. Then, based on some simple conditions, we will also include the Klevu Search Results Theme and optionally the Klevu Category Theme.

Add the following within <head/>, near the top so it will begin loading as quickly as possible after the customer loads your website:

Tip: You may wish to try this on an unpublished theme first, to make sure everything works as you expect.

<!-- Include Klevu JavaScript Library -->
<script src="https://js.klevu.com/core/v2/klevu.js"></script>

<!-- Include Quick Search Theme -->
<script src="https://js.klevu.com/theme/default/v2/quick-search.js"></script>

{% if template == 'page.klevu-search-results' %}
    <!-- Include Search Results Landing Page Theme -->
    <script src="https://js.klevu.com/theme/default/v2/search-results-page.js"></script>

{% elsif template == 'collection'%}
    <!-- Include Category Page Theme -->
    <script src="https://js.klevu.com/theme/default/v2/category-page.js"></script>
    <script type="text/javascript">
      var klevu_pageCategory = "{{ collection.title | escape }}";
      sessionStorage.setItem("klevu_pageCategory", klevu_pageCategory);

{% endif %}

<!-- Initialise Klevu for your store -->
<script type="text/javascript">
    klevu.interactive(function () {
        var options = {
            url : {
                landing: '/pages/search-results', // your Shopify Search Results Page
                search: klevu.settings.url.protocol
                    + '//eucsXXXv2.ksearchnet.com/cs/v2/search' // your Klevu APIv2 Search URL
            search: {
                minChars: 0,
                searchBoxSelector: "input.search-form__input", // your Shopify Search Input
                apiKey: "klevu-XXX" // your Klevu JS API Key
            analytics: {
                apiKey: 'klevu-XXX' // your Klevu JS API Key

There are some small modifications you will need to make to the above code in order to use your Klevu credentials:

  • Landing Page: ‘/pages/search-results’
    This is the URL that we will send customers to when they use your search bar to access the full search results. We will create this page later on in the guide.
  • Search URL: eucsXXXv2.ksearchnet.com/cs/v2/search
    This is your Klevu APIv2 Cloud Search URL. You can find this from Shop Info within your Klevu Merchant Centre.
  • Search Box Selector: “input.search-form__input”
    This is the class or ID to locate your Shopify theme’s input search box. You may need to change this depending on your theme.
  • Api Key: “klevu-XXX”
    This is your public Klevu JS API Key. You can find this from Shop Info within your Klevu Merchant Centre.

Important: If you are not using Klevu Smart Category Merchandising to power your Shopify Collection pages, please omit the section {% elsif template == 'collection'%}.

Create a Search Results Page

Next we need a page to act as the search results landing page. Within your theme editor go to Templates then Add a new template. Create a new template for Page named “klevu-search-results”, and copy in the following:

<div class="page-width">
  <h1>{{ page.title }}</h1>
  <div class="klevuLanding"></div>

Tip: The only important part here for Klevu to function correctly is <div class="klevuLanding"></div>. The rest of the code is to align with your Shopify theme, so feel free to edit accordingly.

Next we need to create a new Page within Shopify which will use this template. Navigate to Online Store > Pages then click Add Page to create a new page. The most important setting is to use Theme template: page.klevu-search-results. For the other settings you can enter as you wish, but we recommend:

  • Title: Search Results
  • Content: (leave this empty)
  • SEO URL and handle: /pages/search-results
  • Theme template: page.klevu-search-results

Important: If you choose a different URL to /pages/search-results, please also update the URL within the theme.liquid settings at the start of this guide.

Collection Pages

This section is only applicable if you have opted for the Klevu add-on to also power your Shopify Collection Pages: Klevu Category Merchandising.

Edit your Shopify Theme once more and navigate to Templates > collection.liquid. Within this file you will see something like:

{% section 'collection-template' %}

Please replace this line with:

<div class="klevuLanding"></div>

With this change, instead of using the native Shopify templating engine to render your category listings, a placeholder will be added where Klevu will inject the theme to power your collection pages.

Try it!

That’s all of the changes complete. Once saved, you can view your frontend (or preview your unpublished theme) to see Klevu powered quick search, search results and collection pages on your Shopify store!

Klevu Quick Search on Shopify

Disable native quick search

Some Shopify themes already have a quick search, so you may find that when you start typing you see both Klevu and Shopify search boxes appearing. The steps to disable this vary from theme to theme, so we recommend you follow your own theme’s instructions to disable the native quick search. For example in the Debut theme there is one setting which you can set to false:

settings: {
    predictiveSearchEnabled: false

Customisations in Shopify

To customise the look and feel of your Klevu implementation, you can follow the platform-agnostic guides within this documentation for Klevu JS Theme customisations. Here you can override the HTML, JavaScript and CSS included by default.

Regardless of whether you installed manually or using our Shopify App, if you are using Klevu JS Theme and want to override a setting like powerUp: { quick: false } (as mentioned in the aforementioned customisations guide), the best place to start is the <head/> section of theme.liquid, as this is where Klevu is usually initialised from.

As for custom HTML, CSS and JS and where to place this, you can add this however you prefer, whether that be directly within the theme.liquid, or via new snippets or sections you create, it is entirely up to you. For example, you could create a new Klevu product template for quick search within a new custom snippet called klevu-custom-quick-search.liquid, and as long as this is included within the HTML of your page and you correctly follow the guide to override a Klevu template, it will work just fine.


If you have any problems, please feel free to reach out to us at community.klevu.com, where you can get help from the Klevu JavaScript development team directly.