Instant Search

A key part of a great e-commerce search experience is getting results immediately as you start typing.

Our Instant Search UI component makes this user experience swift and easy to build.

Adding instant search to a search input

Any Clerk.io Content can be made into an Instant Search Component.

The only thing needed to activate this is to tell the Content to listen for changes on one or more input fields.

This is done by adding the data-instant-search attribute to the content. This should contain a CSS selector matching all the inputs you want the content to listen on.

As soon as a user starts typing in any of the monitored inputs the content will be updated and the content will be moved next to the input field.

<span 
  class="clerk"
  
  data-api="search/predictive"
  data-limit="6"
  data-labels='["Instant Search"]'
      
  data-instant-search="INSERT_CSS_SELECTORS_HERE">
  
  <dl class="product-search-result-list">
    <dt>Products matching <i>{{ query }}</i></dt>
    
    {% for product in products %}
      <dd class="product clerk-instant-search-key-selectable">
        <h2 class="product-name">{{ product.name }}</h2> 
        <img src="{{ product.image }}" title="{{ product.name }}" />
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Buy Now</a>
      </dd>
    {% endfor %}
  </dl>
</span>

Searching suggestions, categories and other content

By default, the instant search will only search for products but can be set to search for both categories and pages.

This is done by adding attributes that specify how many suggestions, categories or pages should be returned as either data-instant-search-suggestions, data-instant-search-categories or data-instant-search-pages. This will make hence a suggestions, categories and pages variable available in the template.

<span 
  class="clerk"
  
  data-api="search/predictive"
  data-limit="6"
      
  data-instant-search="INSERT_CSS_SELECTORS_HERE"
  
  data-instant-search-suggestions="3"
  data-instant-search-categories="6"
  data-instant-search-pages="6">
  
  <dl class="product-search-result-list">
    <h2>Search results for <i>{{ query }}</i></h2>
    
    <!-- Show query suggestions -->
    {% if suggestions.length > 0 %}
      <dt>Suggestions</dt>
    
      {% for suggestion in suggestions %}
        <dd class="suggestion clerk-instant-search-key-selectable">
          <a href="/search/?query={{ suggestion }}">
            {{ suggestion }}
          </a>
        </dd>
      {% endfor %}
    {% endif %}
    
    <!-- Show categories if there were any match -->
    {% if categories.length > 0 %}
      <dt>Categories</dt>
    
      {% for category in categories %}
        <dd class="category clerk-instant-search-key-selectable">
          <a href="{{ category.url }}">
            <p class="category-name">{{ category.name }}</p>
          </a>
        </dd>
      {% endfor %}
    {% endif %}
    
    <!-- Show products if there were any match -->
    {% if products.length > 0 %}
      <dt>Products</dt>
    
      {% for product in products %}
        <dd class="product clerk-instant-search-key-selectable">
          <h2 class="product-name">{{ product.name }}</h2> 
          <img src="{{ product.image }}" title="{{ product.name }}" />
          <div class="price">${{ product.price | money }}</div>
          <a href="{{ product.url }}">Buy Now</a>
        </dd>
      {% endfor %}
    {% endif %}
    
    <!-- Show pages if there were any match -->
    {% if pages.length > 0 %}
      <dt>Pages</dt>
    
      {% for page in pages %}
        <dd class="page clerk-instant-search-key-selectable">
          <a href="{{ page.url }}">
            <p class="page-title">{{ page.title }}</p>
          </a>
        </dd>
      {% endfor %}
    {% endif %}
  </dl>
</span>

Keyboard navigation

Instant search support full keyboard navigation using the up- and down-keys for selecting elements and selecting them with the enter key.

Any element with the class clerk-instant-search-key-selectable will be keyboard navigatable no matter the type. Elements will be navigated in their DOM order.

When an element is selected it will have the class clerk-instant-search-key-selected to be used for styling purposes.

When enter is pressed we will look for something to click on in .clerk-instant-search-key-selected so remember to have a link in your markup.

Instant search positioning

The instant search will by default position itself just under the active search input field and adapt to the same width.

This behavior is fully customizable by changing the positioning mode via the data-instant-search-positioning attribute.

Disable query autofill upon hitting enter

When using instant search we predict what query the customer is typing right now even though that's not what's typed in the search field. To give a smooth search experience we auto-fill the input field when the customer hits enter so they can continue the same search ion the search page.

If you wish to disable this feature please just add the attribute data-autofill="false" to the instant search embed code.

Visual customisation

By default, the instant search will do no visual customisation to you instant search, allowing you full control via CSS.

For easier styling, the root container element will get the class clerk-instant-search-container.

To toggle the instant search visibility the classes clerk-instant-search-visible and clerk-instant-search-hidden are used and can be fully overwritten.