AddSearch Search UI Library

Use Search UI library to create fast, mobile-friendy, and cross-browser compatible search solutions quickly and effortlessly.

Open the demo

Quick example

<!-- Libraries -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/addsearch-js-client.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/addsearch-search-ui.min.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/addsearch-search-ui.min.css" />

<!-- Containers for UI components-->
<div id="searchfield-container"></div>
<div id="results-container"></div>
<div id="pagination-container"></div>

<script>
  // AddSearch JS client instance
  var client = new AddSearchClient('YOUR PUBLIC SITEKEY');

  // Search UI instance
  var searchui = new AddSearchUI(client);

  // UI components
  searchui.searchField({
    containerId: 'searchfield-container',
    placeholder: 'Keyword..',
    button: 'Search'
  });

  searchui.searchResults({
    containerId: 'results-container'
  });
  
  searchui.pagination({
    containerId: 'pagination-container'
  });
  
  // Start after all components are added
  searchui.start();
</script>

Examples

Basic example

• Try it out
• View source code

Advanced example with many components

• Try it out
• View source code

See more examples

• All examples
• View source code

Search UI instance and configuration

To create a Search UI instance, call the constructor new AddSearchUI(client, conf) with the mandatory AddSearchClient (v0.3.0 or newer) parameter and an optional configuration parameter:

var client = new AddSearchClient('YOUR PUBLIC SITEKEY');

var conf = {
  debug: true
};

var searchui = new AddSearchUI(client, conf);

The configuration object can contain following values:

After all UI components have been added to the SearchUI object, the start function must be called:

  searchui.start();

Components

Search field

The search field. Can include a button to execute the search.

  searchui.searchField({
    containerId: 'searchfield',
    placeholder: 'Keyword..',
    button: 'Search'
  });

Settings that can be passed to the searchField function:

Autocomplete

Show suggested keyword, search results, or both under the search field. The default autocomplete template supports search suggestions that must be enabled from the AddSearch Dashboard before using the feature. Create your own template if you want to to show search results or more advanced views.

  searchui.autocomplete({
    containerId: 'autocomplete',
    sources: [
      {
        type: AddSearchUI.AUTOCOMPLETE_TYPE.SUGGESTIONS
      }
    ]
  });

Settings that can be passed to the autocomplete function:

The sources array can contain objects with the following fields:

Search results

Actual search results.

  searchui.searchResults({
    containerId: 'searchresults'
  });

Settings that can be passed to the searchResults function:

If you are customising the default search result template, make sure your links still include the data-analytics-click="{{id}}" attribute, otherwise your analytics will not report clicks or CTR correctly.

Pagination

Pagination. Typically below search results.

  searchui.pagination({
    containerId: 'pagination'
  });

Settings that can be passed to the pagination function:

To change the number of results shown per page, use AddSearch JS client's setPaging function

Load more results

Button to load more results or an infinite scroll implementation.

  searchui.loadMore({
    containerId: 'loadmore',
    type: AddSearchUI.LOAD_MORE_TYPE.BUTTON
  });

Settings that can be passed to the loadMore function:

To change the number of results shown per page, use AddSearch JS client's setPaging function. The same Search UI can have the pagination component for desktop view and loadMore for mobile.

Sort by

Component to change the order of search results.

  searchui.sortBy({
    containerId: 'sortby',
    options: [
      {
        label: 'Sort by relevance',
        sortBy: 'relevance',
        order: 'desc'
      },
      {
        label: 'Oldest first',
        sortBy: 'date',
        order: 'asc'
      },
      {
        label: 'Most expensive first',
        sortBy: 'custom_fields.price',
        order: 'desc'
      },
      {
        label: 'Multiple sorting parameters',
        sortBy: ['custom_fields.plan_name', 'date'],
        order: ['desc', 'desc']
      }
    ]
  });

Settings that can be passed to the sortBy function:

The options array can contain objects with following fields:

Filters

Components to let the user filter search results by URL patterns or custom field values.

  searchui.filters({
    containerId: 'filters',
    type: AddSearchUI.FILTER_TYPE.CHECKBOX_GROUP,
      options: {
        appleProducts: {
          label: 'Apple products',
          filter: {'custom_fields.brand': 'apple'}
        }
    }
  });

Settings that can be passed to the filters function:

The options object can contain multiple filtering options. If the type is Tabs, Select list, or Radio group, just one of the options can be activated at any given time. If the filter type is Checkbox or Tags, multiple filters can be activated. The option key (appleProducts in the example above) is shared across filter components. All filters with the same key are enabled and disabled simultaneously. Because of this, you can have several filter components controlling the same filter. For example, radio button list on desktop view and a select list on mobile.

Fields in options:

The options object is not applicable if the filter type is AddSearchUI.FILTER_TYPE.RANGE, but following settings should be passed to the filters function:

Facets

Display facets and let the user filter results by facets (i.e. dynamic property filters).

  searchui.facets({
    containerId: 'facets'
  });

Before using this component, add appropriate facets to your client instance so the information is fetched from the search index:

  client.addFacetField('custom_fields.brand');

Settings that can be passed to the facets function:

Hierarchical Facets

Display hierarchical facets and let the user filter results by facets. In addition, user can drill down each facets and select more specific values. (i.e. dynamic property filters). By default, hierarchical facet is sticky. Currently, this component does not support historical URL, refreshing the page will lose the current state of the facet group.

  searchui.hierarchicalFacets({
    containerId: 'hierarchical-facets-container',
    fields: [
      'custom_fields.nested_facet_lvl_0',
      'custom_fields.nested_facet_lvl_1',
      'custom_fields.nested_facet_lvl_2',
      'custom_fields.nested_facet_lvl_3'
    ]
  });

Before using this component, add appropriate hierarchical facets to your client instance so the information is fetched from the search index:

  client.addHierarchicalFacetSetting([
    {
      "fields": [
       "custom_fields.nested_facet_lvl_0",
        "custom_fields.nested_facet_lvl_1",
       "custom_fields.nested_facet_lvl_2",
        "custom_fields.nested_facet_lvl_3"
      ],
      "sortOrder": "COUNT_DESC_NAME_ASC"
    }
  ]);

Settings that can be passed to the facets function:

Range Facets

Display range facets of a given custom field and let the user filter results by different range buckets. By default, range facet is sticky. This feature uses extra search queries to fetch min-max values of the custom field.

  client.addStatsField('custom_fields.price');
  searchui.rangeFacets({
    containerId: 'rangeFacetsContainer',
    field: 'custom_fields.price',
    maxNumberOfRangeBuckets: 7
  });

Settings that can be passed to the rangeFacets function:

Active filters

Show active filters and facets. Let user remove specific filters or clear everything,

  searchui.activeFilters({
    containerId: 'activefilters'
  });

Settings that can be passed to the activeFilters function:

Segmented search results

Show multiple search results lists from several indices or with different filters.

  searchui.segmentedSearchResults({
    containerId: 'segment1',
    client: segmentClient,
    template: segmentTemplate
  });

Settings that can be passed to the segmentedSearchResults function:

Frequently bought together

Show frequently bought together items given the product ID.

  searchui.recommendations({
    containerId: 'recommendation-container',
    type: AddSearchUI.RECOMMENDATION_TYPE.FREQUENTLY_BOUGHT_TOGETHER,
    configurationKey: 'config1',
    getProductIdFunction: function() {
      return new URLSearchParams(window.location.search).get('prod');
    },
    ignoreFetchOnStart: false
  });

Settings that can be passed to the segmentedSearchResults function:

General functions

Execute search

Execute a search query with a specific keyword. Common use cases include links of most popular keywords: Clicking the keyword executes the search.

  searchui.search(keyword);

Clear search

Clear the keyword and enabled filters.

  searchui.clear();

Hide autocomplete

Hide the autocomplete component. For example, a "close" button inside the autocomplete modal would call this function.

  searchui.hideAutocomplete();

Register a custom Handlebars helper

Handlebars Helpers can be used to implement functionality that is not part of the Handlebars language itself. Read more at handlebarsjs.js.

  // This function can be called in a Handlebars template: {{toUpperCase "foo"}}
  searchui.registerHandlebarsHelper('toUpperCase', function(param) {
    return param.toUpperCase();
  });

Register a custom Handlebars partial

Handlebars allows for template reuse through partials. Partials are normal Handlebars templates that may be called directly by other templates. Read more at handlebarsjs.js.

  // This function can be called in a Handlebars template: {{toUpperCase "foo"}}
  var partialTemplate = `Print this line in main template.`;
  searchui.registerHandlebarsPartial('myPartial', partialTemplate);

  // Calling the partial in main template
  {{> myPartial}}

Analytics

This library sends analytics events to AddSearch Analytics Dashboard when:

• Search results are returned
• No results were found
• A result was clicked

You can add integration for third party analytics software by passing a custom analyticsCallback function in AddSearchClient constructor's configuration object. This function is called with a single parameter containing one of the following JSON objects:

Search results received:

{
  action: 'search', 
  keyword: 'keyword', 
  numberOfResults: 10, // If 0, no results were found
  processingTimeMs: 21 // Time it took to process the query and return search results (in milliseconds)
}

In search-as-you-type implementations the search event is sent after 2,5 second delay in typing or if a result is clicked within this debounce time.

Search result clicked:

{
  action: 'click', 
  keyword: 'keyword', 
  documentId: '...', // Hit's 32-char identifier
  position: 1 // Position of the clicked result. The first result being 1
}

To save clicks reliably before the user's browser leaves the page, it's recommended to use the navigator.sendBeacon method.

Supported web browsers

This library is tested on

• Chrome
• Firefox
• Edge
• Safari 6.1+
• Internet Explorer 11

Development

To modify this library, clone the repository and follow these steps:

Install dependencies

npm install

Code

Re-compile when source files change while developing

npm run watch

Run tests

Run automated tests

npm test

Run automatically when tests change

npm run test -- --watch

Build for production

Build a production bundle. The file is saved under the dist/ folder

npm run build

Support

Feel free to send any questions, ideas, and suggestions at [email protected] or visit addsearch.com for more information.