Getting Started with Search

Search API is coming late Q1 2023
To get started with Search on your website, navigate to the Search tab under 'On-site' within the Nosto UI. This is where everything for Search can be configured and controlled, including designing the templates for search pages and autocomplete dropdowns, as well as search analytics, query rules and other settings. Synonyms for search queries can also be configured here.
To begin implementing Search, navigate to the Templates tab, and click on “Open Code Editor”.
Nosto Admin UI > Search
You will then be redirected to the VSCode Editor window. On the left-hand side is the project structure panel, and on the right-hand side is the very familiar code-editor panel. Note the components defined for both the Search Page and the Autocomplete dropdown. These components can be used to define and extend behaviour on your website.
VSCode Editor
Why use the VSCode Editor?
Search functionality can be implemented on your website, all while customising the look and feel of how search pages and search autocomplete boxes are rendered through this editor. We provide flexibility to apply any merchant-defined design, as well as other functionalities, for e.g., a custom “Add to wishlist” button.
There is a default design already in place that allows merchants to get started with a pre-implemented easy-to-understand design, which can be extended and modified as required.

Setting Up

index.js should be used to bind Search on your website.
The inputCssSelector param can be used for this purpose. If there is an existing Search on your website, you can copy the CSS selector for it by highlighting the search box through the developer tools on your browser, and then right-click and ‘Copy selector’.
We will also need to unbind any existing Search within the page. To achieve this, a new function can be introduced (similar to the one below) that will help unbind the original Search functionality and replace it with Nosto's Search. This can be done in helpers.js, for example.
export function unbindOriginalSearch(selector) {
const elements = document.querySelectorAll(selector);
elements.forEach(el => {
var newElement = el.cloneNode(true);
el.parentNode.replaceChild(newElement, el);
This can then be called from within index.js, just before the init() function. The call can pass in the CSS selector that we copied earlier from the website, unbindOriginalSearch('#search_form')


Listed below are how the different components under serp and autocomplete will be used to render different sections on the Search Page and the Autocomplete box.

Search Page (serp)


Design of the toolbar at the button of the page. This can be used for displaying the number of pages, page count, items per page, etc.


Design of the facets. For example, the product colour, size, and other filters the user may wish to apply to the search results.


Design of the loading page, while search results are retrieved and rendered. This is shown while the search results load. By default, this will be a throbber/loading icon.


Page to show that there were no results found.


Design for changing pages, usually shown below the BottomToolbar. It can be used to design the way the user changes the page.


Design of how the product listings show up on the search page. This can be used to control how many products are shown on the result page, as well as the design of how they are displayed.

Search Autocomplete (autocomplete)

Design of the autocomplete box as the user enters their search query. This is usually shown just below the search box, and updates in real time. It features product suggestions to help users view the top matches with their query, even before the search page loads.


All these components can be customised further with the .css files under styles.

Rendering the autocomplete dropdown on click

To open up the autocomplete dropdown when the user clicks into the search box, pass in a length of 0 to the autocompleteMinLength via the init() function in index.js. There is already a callback defined in the library to handle displaying the dropdown once this is set to 0.
Additionally, content can be displayed on the "empty" autocomplete dropdown (since no search query is fired when this opens up). This can be done by modifying autocomplete/index.jsx in the manner below.
if (!products?.hits?.length && config.autocompleteMinLength !== 0) {
This will enable the dropdown of the autocomplete box when the user clicks into it, though content or text will need to be added.

Rendering autocomplete based on a CSS selector

The autocomplete box can be rendered anywhere on the page via a CSS selector. This can be passed in via the init() function as well. The prop is dropdownCssSelector.

Changing URL mappings

By default, the URL mappings are as below.
serpUrlMapping: {
name: 'name',
query: 'query',
segments: 'segments',
customRules: 'customRules',
explain: 'explain',
time: 'time',
products: 'products',
keywords: 'keywords'
This can be changed as desired and passed into init() as required. Changing the mapping can be handy for use cases where Google Analytics has been set up to track one parameter for query (like 'q') but Search comes with the default 'query'.

Sort options and other customisations

All sorting options can be controlled via config.js, where the field on which the sorting is applied can be changed.
This is also where the default page size can be changed.

RangeFacet customisations

As an example of how to customise the RangeFacet further, we can see how to pass in props for the RangeSlider and change the way your currency format can be changed to the desired output.
Cmd + click on the RangeSlider component to see what props can be passed in.
RangeSlider component
The valueFormat prop here can be used to pass in a callback function for formatting the resulting range values from a number to a currency. There already exists a function in helpers.js called formatCurrency(), which we can pass in as a RangeSlider prop in the manner described below.
valueFormat={formatCurrency} />
This will now format the values accordingly. The implementation of formatCurrency() can be changed to fit your requirements.

Adding Search scripts to your website

Once you have the Nosto script added to your store through the steps mentioned on previous pages (e.g., Adding the Nosto Script), and Search enabled through the backend (you can check via the Nosto Admin UI), these template scripts should load automatically upon initialisation. If set up correctly, you should then already see Search in action!
There is no need for any additional setup.
To preview an undeployed design on your website, and test your changes from the VSCode Editor:
  1. 1.
    Navigate to your website
  2. 2.
    In the URL, append ?nostodebug=true to enable the debug toolbar
  3. 3.
    The Nosto debug toolbar should open up, where you will be asked to log in
  4. 4.
    Once you have logged in, enable the Preview toggle button at the bottom
  5. 5.
    You should now be able to view your changes live, via the Search box
  6. 6.
    As you make changes in the VSCode Editor, you can test out how Search will show on your website live
Through this method, you can view changes even when there is no deployment. If changes are deployed, the current changes from the VSCode Editor are loaded instead of the deployed version.
All that is needed to test are compiled changes from the Editor, which are auto-saved and can be compiled with Cmd-S.

Rollback & Disable

Rollback previous deployment

  1. 1.
    Navigate to the Nosto Admin UI > Search > Templates
  2. 2.
    Click on the desired deployment and then click on "Redeploy"

Disable Search Templates (in case of an emergency)

  1. 1.
    Navigate to the Nosto Admin UI > Search > Templates
  2. 2.
    Click on the “Disable Templates” button.
  3. 3.
    This will disable Search completely, and bind the original Search again
  4. 4.
    Once you have addressed the issues with the templates, click "Deploy latest" and Search will be back in action!
For any other questions, please feel free to contact Nosto support. We will be happy to help you out!