InstantSearch widget that makes a sort-by

Usage no npm install needed!

<script type="module">
  import algoliaInstantsearchWidgetSortbyUl from 'https://cdn.skypack.dev/@algolia/instantsearch-widget-sortby-ul';



InstantSearch.js widget displaying a list of indices, allowing a user to change the way hits are sorted. Equivalent of the offcial sortby widget using <ul><li> markups instead of <select>.

MIT NPM version


Get started


Demo on CodeSandbox.


npm install @algolia/instantsearch-widget-sortby-ul
# or
yarn add @algolia/instantsearch-widget-sortby-ul


import instantsearch from 'instantsearch.js';
import algoliasearch from 'algoliasearch/lite';
import { sortBy } from '@algolia/instantsearch-widget-sortby-ul';

const searchClient = algoliasearch('appId', 'apiKey');

const search = instantsearch({
  indexName: 'indexName',

    container: '#sort-by' // or document.querySelector('#sort-by')
    items: [
      { value: 'instant_search', label: 'Most relevant' },
      { value: 'instant_search_price_asc', label: 'Lowest price' },
      { value: 'instant_search_price_desc', label: 'Highest price' },



Option Type Required Default Description
container string or HTMLElement true - The element to insert the widget into.
items object[] true - The list of indices to search in.
cssClasses object false {} The CSS classes to override.
transformItems function false items => items Receives the items, and is called before displaying them.


string | HTMLElement | required

The element to insert the widget into.

This can be either a valid CSS Selector:

  container: '#sort-by',
  // ...

or an HTMLElement:

  container: document.querySelector('#sort-by'),
  // ...


object[] | required

The list of indices to search in, with each item:

  • label: string: the label of the index to display.
  • value: string: the name of the index to target.
  items: [
    { label: 'Featured', value: 'instant_search' },
    { label: 'Price (asc)', value: 'instant_search_price_asc' },
    { label: 'Price (desc)', value: 'instant_search_price_desc' },
  // ...


object | optional

The CSS classes to override.

  • root: the root element of the widget.
  • list: the <ul> element.
  • item: each <li> element.
  // ...
  cssClasses: {
    root: 'MyCustomSortByUL',
    list: 'MyCustomSortByUL MyCustomSortByUL--subclass',


function | optional

Receives the items, and is called before displaying them. Should return a new array with the same shape as the original array. Useful for mapping over the items to transform, and remove or reorder them.

  // ...
  transformItems(items) {
    return items.map(item => ({
      label: item.label.toUpperCase(),

Browser support

Same as InstantSearch.js it supports the last two versions of major browsers (Chrome, Edge, Firefox, Safari).

Please refer to the browser support section in the documentation to use InstantSearch.js and this widget on other browsers.


Encountering an issue? Before reaching out to support, we recommend heading to our FAQ where you will find answers for the most common issues and gotchas with the library.

Contributing & Licence

How to contribute

We welcome all contributors, from casual to regular 💙

  • Bug report. Is something not working as expected? Send a bug report.
  • Feature request. Would you like to add something to the library? Send a feature request.
  • Documentation. Did you find a typo in the doc? Open an issue and we'll take care of it.
  • Development. If you don't know where to start, you can check the open issues that are tagged easy, the bugs or chores.

To start contributing to code, you need to:

  1. Fork the project
  2. Clone the repository
  3. Install the dependencies: yarn
  4. Run the development mode: yarn start
  5. Open the stories

Please read our contribution process to learn more.


Licensed under the MIT license.

About InstantSearch.js

InstantSearch.js is a vanilla JavaScript library that lets you create an instant-search result experience using Algolia’s search API. It is part of the InstantSearch family:

InstantSearch.js | React InstantSearch | Vue InstantSearch | Angular InstantSearch | React InstantSearch Native | InstantSearch Android | InstantSearch iOS

This project was generated with create-instantsearch-app by Algolia.