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>.

Summary

• Demo
• Installation
• Usage
• Options
• Browser Support
• Troubleshooting
• Contributing & Licence

Get started

Demo

Demo on CodeSandbox.

Install

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

Usage

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',
  searchClient,
});

search.addWidgets([
  sortBy({
    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' },
    ],
  }),
]);

search.start();

Options

| 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. |

container

string | HTMLElement | required

The element to insert the widget into.

This can be either a valid CSS Selector:

sortBy({
  container: '#sort-by',
  // ...
});

or an HTMLElement:

sortBy({
  container: document.querySelector('#sort-by'),
  // ...
});

items

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.

sortBy({
  items: [
    { label: 'Featured', value: 'instant_search' },
    { label: 'Price (asc)', value: 'instant_search_price_asc' },
    { label: 'Price (desc)', value: 'instant_search_price_desc' },
  ],
  // ...
});

cssClasses

object | optional

The CSS classes to override.

• root: the root element of the widget.
• list: the <ul> element.
• item: each <li> element.

sortBy({
  // ...
  cssClasses: {
    root: 'MyCustomSortByUL',
    list: 'MyCustomSortByUL MyCustomSortByUL--subclass',
  },
});

transformItems

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.

sortBy({
  // ...
  transformItems(items) {
    return items.map(item => ({
      ...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.

Troubleshooting

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.

Licence

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.