<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.
<SortBy items={object[]} // Optional parameters transformItems={function} classNames={object} ...props={ComponentProps<'div'>} />
1
import { SortBy } from 'react-instantsearch';
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import React from 'react';
import { liteClient as 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
items
|
type: SortByProps['items']
Required
A list of different indices to choose from. |
||
Copy
|
|||
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 |
||
Copy
|
|||
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.
|
||
Copy
|
|||
...props
|
type: React.ComponentProps<'div'>
Optional
Any |
||
Copy
|
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.
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.
items
|
type: UseSortByProps['items']
Required
A list of different indices to choose from. |
||
Copy
|
|||
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 |
||
Copy
|
APIs
Hooks return APIs, such as state and functions. You can use them to build your UI and interact with React InstantSearch.
initialIndex
|
type: string
The initially selected index. |
||
currentRefinement
|
type: string
The currently selected index. |
||
options
|
type: SortByItem[]
All the available indices.
Copy
|
||
refine
|
type: (value: string) => void
Switches indices and triggers a new search. |
||
canRefine
|
type: boolean
Whether the search can be refined. |
Example
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>
);
}