UI libraries / React InstantSearch / Widgets

<SortBy>

This is the React InstantSearch v7 documentation. React InstantSearch v7 is the latest version of React InstantSearch and the stable version of React InstantSearch Hooks.

If you were using React InstantSearch v6, you can upgrade to v7.

If you were using React InstantSearch Hooks, you can still use the React InstantSearch v7 documentation, but you should check the upgrade guide for necessary changes.

If you want to keep using React InstantSearch v6, you can find the archived documentation.

Signature 
<SortBy
  items={object[]}
  // Optional parameters
  transformItems={function}
  classNames={object}
  ...props={ComponentProps<'div'>}
/>
Import
Copy 
1

import { SortBy } from 'react-instantsearch';
See code examples
See live example

About this widget

<SortBy> is a widget to sort by specified indices.

This lets you display a list of indices users to select, allowing them to change how hits are sorted using replica indices.

You must set all indices you define in items as replicas of the main index.

You can also create your own UI with useSortBy().

Examples

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

import React from 'react';
import algoliasearch from 'algoliasearch/lite';
import { InstantSearch, SortBy } from 'react-instantsearch';

const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <SortBy
        items={[
          { label: 'Featured', value: 'instant_search' },
          { label: 'Price (asc)', value: 'instant_search_price_asc' },
          { label: 'Price (desc)', value: 'instant_search_price_desc' },
        ]}
      />
    </InstantSearch>
  );
}

Props

Parameter Description
items
type: SortByProps['items']
Required

A list of different indices to choose from.
Copy 
1
2
3
4
5
6
7

<SortBy
  items={[
    { label: 'Featured', value: 'instant_search' },
    { label: 'Price (asc)', value: 'instant_search_price_asc' },
    { label: 'Price (desc)', value: 'instant_search_price_desc' },
  ]}
/>
transformItems
type: (items: object[], metadata: { results: SearchResults }) => object[]

Receives the items and is called before displaying them. Should return a new array with the same shape as the original array. Useful for transforming, removing, or reordering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

const transformItems = (items) => {
  return items.map((item) => ({
    ...item,
    label: item.label.toUpperCase(),
  }));
};

function Search() {
  return (
    <SortBy
      // ...
      transformItems={transformItems}
    />
  );
}
classNames
type: Partial<SortByClassNames>
Optional

The CSS classes you can override and pass to the widget’s elements. It’s useful to style widgets with class-based CSS frameworks like Bootstrap or Tailwind CSS.

  • root: The root element of the widget.
  • select: The select element.
  • option: The option element.
Copy 
1
2
3
4
5
6
7

<SortBy
  // ...
  classNames={{
    root: 'MyCustomSortBy',
    select: 'MyCustomSortBySelect MyCustomSortBySelect--subclass',
  }}
/>
...props
type: React.ComponentProps<'div'>
Optional

Any <div> prop to forward to the root element of the widget.
Copy 
1
2
3
4
5

<SortBy
  // ...
  className="MyCustomSortBy"
  title="My custom title"
/>

Hook

React InstantSearch let you create your own UI for the <SortBy> widget with useSortBy(). Hooks provide APIs to access the widget state and interact with InstantSearch.

The useSortBy() Hook accepts parameters and returns APIs.

See code examples

Usage

First, create your React component:

import { useSortBy } from 'react-instantsearch';

function CustomSortBy(props) {
  const {
    initialIndex,
    currentRefinement,
    options,
    refine,
    canRefine,
  } = useSortBy(props);

  return <>{/* Your JSX */}</>;
}

Then, render the widget:

<CustomSortBy {...props} />

Parameters

Hooks accept parameters. You can pass them manually, or forward the props from your custom component.

When you provide a function to Hooks, make sure to pass a stable reference to avoid rendering endlessly (for example, with useCallback()). Objects and arrays are memoized; you don’t need to stabilize them.

Parameter Description
items
type: UseSortByProps['items']
Required

A list of different indices to choose from.
Copy 
1
2
3
4
5
6
7

const sortByApi = useSortBy({
  items: [
    { label: 'Featured', value: 'instant_search' },
    { label: 'Price (asc)', value: 'instant_search_price_asc' },
    { label: 'Price (desc)', value: 'instant_search_price_desc' },
  ],
});
transformItems
type: (items: object[], metadata: { results: SearchResults }) => object[]

Receives the items and is called before displaying them. Should return a new array with the same shape as the original array. Useful for transforming, removing, or reordering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

const transformItems = (items) => {
  return items.map((item) => ({
    ...item,
    label: item.label.toUpperCase(),
  }));
};

function SortBy() {
  const sortByApi = useSortBy({
    // ...
    transformItems,
  });

  return <>{/* Your JSX */}</>;
}

APIs

Hooks return APIs, such as state and functions. You can use them to build your UI and interact with React InstantSearch.

Parameter Description
initialIndex
type: string

The initially selected index.
currentRefinement
type: string

The currently selected index.
options
type: SortByItem[]

All the available indices.

Copy 
1
2
3
4
5
6
7
8
9
10

type SortByItem = {
  /**
   * The name of the index to target.
   */
  value: string;
  /**
   * The label of the index to display.
   */
  label: string;
};
refine
type: (value: string) => void

Switches indices and triggers a new search.
canRefine
type: boolean

Whether the search can be refined.

Example

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

import React from 'react';
import { useSortBy } from 'react-instantsearch';

function SortBy(props) {
  const { currentRefinement, options, refine } = useSortBy(props);

  return (
    <select
      onChange={(event) => refine(event.target.value)}
      value={currentRefinement}
    >
      {options.map((option) => (
        <option key={option.value} value={option.value}>
          {option.label}
        </option>
      ))}
    </select>
  );
}
Did you find this page helpful?
React InstantSearch v7