API Reference / React InstantSearch / SortBy

SortBy

A
Signature 
<SortBy
  items={object[]}
  defaultRefinement={string}
  // Optional parameters
  transformItems={function}
/>
See code examples
See live example

About this widget # A

We released React InstantSearch Hooks, a new InstantSearch library for React. We recommend using React InstantSearch Hooks in new projects or upgrading from React InstantSearch.

The SortBy widget displays a list of indices, allowing a user to change the way hits are sorting (with replica indices). Another common use case for this widget is to let the user switch between different indices.

For this widget to work, you must define all indices that you pass down as options as replicas of the main index.

Examples # A

Copy 
1
2
3
4
5
6
7
8
9
10

import { SortBy } from 'react-instantsearch-dom';

<SortBy
  defaultRefinement="instant_search"
  items={[
    { value: 'instant_search', label: 'Featured' },
    { value: 'instant_search_price_asc', label: 'Price asc.' },
    { value: 'instant_search_price_desc', label: 'Price desc.' },
  ]}
/>

Props # A

items #
type: object[]
Required

The list of indices to search in.
Copy 
1
2
3
4
5
6
7
8

<SortBy
  // ...
  items={[
    { value: 'instant_search', label: 'Featured' },
    { value: 'instant_search_price_asc', label: 'Price asc.' },
    { value: 'instant_search_price_desc', label: 'Price desc.' },
  ]}
/>
defaultRefinement #
type: string
Required

The index selected by default.
Copy 
1
2
3
4

<SortBy
  // ...
  defaultRefinement="instant_search"
/>
transformItems #
type: function
default: items => items
Optional

Modifies the items being displayed, for example, to filter or sort them. Takes items as argument and expects them back in return.
Copy 
1
2
3
4
5
6
7
8
9

<SortBy
  // ...
  transformItems={items =>
    items.map(item => ({
      ...item,
      label: item.label.toUpperCase(),
    }))
  }
/>

HTML output# A

Copy 
1
2
3
4
5
6
7

<div class="ais-SortBy">
  <select class="ais-SortBy-select">
    <option class="ais-SortBy-option" value="instant_search">Featured</option>
    <option class="ais-SortBy-option" value="instant_search_price_asc">Price asc.</option>
    <option class="ais-SortBy-option" value="instant_search_price_desc">Price desc.</option>
  </select>
</div>

Customize the UI with connectSortBy# A

If you want to create your own UI of the SortBy widget or use another UI library, you can use connectors.

Connectors are higher-order components. They encapsulate the logic for a specific kind of widget and they provide a way to interact with the InstantSearch context.

They have an outer component API that we call exposed props, and they provide some other props to the wrapped components which are called the provided props.

It’s a 3-step process:

// 1. Create a React component
const SortBy = () => {
  // return the DOM output
};

// 2. Connect the component using the connector
const CustomSortBy = connectSortBy(SortBy);

// 3. Use your connected widget
<CustomSortBy />

See code examples

Create a React component#

const SortBy = ({
  object[] items,
  string currentRefinement,
  function refine,
  function createURL,
}) => {
  // return the DOM output
};

Provided Props#

items #
type: object[]

The list of items the widget can display, with each item:

  • label: string: the label for the option.
  • value: string: the value for the option.
  • isRefined: boolean: whether the refinement is selected.
Copy 
1
2
3
4
5
6
7
8
9

const SortBy = ({ items }) => (
  <ul>
    {items.map(item => (
      <li key={item.value} style={{ fontWeight: item.isRefined ? 'bold' : '' }}>
        {item.label}
      </li>
    ))}
  </ul>
);
currentRefinement #
type: string

The currently applied refinement.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

const SortBy = ({ items, currentRefinement, refine }) => (
  <div>
    <p>
      The search display the index <code>{currentRefinement}</code>.
    </p>
    <ul>
      {items.map(item => (
        <li key={item.value}>
          <a
            href="#"
            style={{ fontWeight: item.isRefined ? 'bold' : '' }}
            onClick={event => {
              event.preventDefault();
              refine(item.value);
            }}
          >
            {item.label}
          </a>
        </li>
      ))}
    </ul>
  </div>
);
refine #
type: function

Switches indices and triggers a new search.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

const SortBy = ({ items, refine }) => (
  <ul>
    {items.map(item => (
      <li key={item.value}>
        <a
          href="#"
          style={{ fontWeight: item.isRefined ? 'bold' : '' }}
          onClick={event => {
            event.preventDefault();
            refine(item.value);
          }}
        >
          {item.label}
        </a>
      </li>
    ))}
  </ul>
);
createURL #
type: function

Generates a URL for the corresponding search state.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

const SortBy = ({ items, createURL }) => (
  <ul>
    {items.map(item => (
      <li key={item.value}>
        <a
          href={createURL(item.value)}
          style={{ fontWeight: item.isRefined ? 'bold' : '' }}
        >
          {item.label}
        </a>
      </li>
    ))}
  </ul>
);

Create and instantiate your connected widget#

const CustomSortBy = connectSortBy(SortBy);

<CustomSortBy
  items={object[]}
  defaultRefinement={string}
  // Optional parameters
  transformItems={function}
/>

Exposed Props#

items #
type: object[]
Required

The list of indices to search in.
Copy 
1
2
3
4
5
6
7
8

<CustomSortBy
  // ...
  items={[
    { value: 'instant_search', label: 'Featured' },
    { value: 'instant_search_price_asc', label: 'Price asc.' },
    { value: 'instant_search_price_desc', label: 'Price desc.' },
  ]}
/>
defaultRefinement #
type: string
Required

The index selected by default.
Copy 
1
2
3
4

<CustomSortBy
  // ...
  defaultRefinement="instant_search"
/>
transformItems #
type: function
default: items => items
Optional

Modifies the items being displayed, for example, to filter or sort them. Takes items as argument and expects them back in return.
Copy 
1
2
3
4
5
6
7
8
9

<CustomSortBy
  // ...
  transformItems={items =>
    items.map(item => ({
      ...item,
      label: item.label.toUpperCase(),
    }))
  }
/>

Full example#

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

import { connectSortBy } from 'react-instantsearch-dom';

const SortBy = ({ items, refine, createURL }) => (
  <ul>
    {items.map(item => (
      <li key={item.value}>
        <a
          href={createURL(item.value)}
          style={{ fontWeight: item.isRefined ? 'bold' : '' }}
          onClick={event => {
            event.preventDefault();
            refine(item.value);
          }}
        >
          {item.label}
        </a>
      </li>
    ))}
  </ul>
);

const CustomSortBy = connectSortBy(SortBy);
Did you find this page helpful?
React InstantSearch v6