SortBy

Shows a list of indices for alternative sorting or ranking of search results.

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.

Signature

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

Import

JavaScript

import { SortBy } from "react-instantsearch";

See this widget in action

Preview this widget and its behavior.

About this widget

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

You can also create your own UI with useSortBy.

Requirements

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

Examples

JavaScript

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 · SortByProps['items'] · required

A list of different indices to choose from.

JavaScript

<SortBy
  items={[
    { label: "Featured", value: "instant_search" },
    { label: "Price (asc)", value: "instant_search_price_asc" },
    { label: "Price (desc)", value: "instant_search_price_desc" },
  ]}
/>;

transformItems · (items: object[], metadata: { results: SearchResults }) => object[]

A function that receives the list of items before they are displayed. It should return a new array with the same structure. Use this to transform, filter, or reorder the items.

The function also has access to the full results data, including all standard response parameters and parameters from the helper, such as disjunctiveFacetsRefinements.

JavaScript

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

function Search() {
  return (
    <SortBy
      // ...
      transformItems={transformItems}
    />
  );
}

import type { SortByProps } from 'react-instantsearch';

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

function Search() {
  return (
    <SortBy
      // ...
      transformItems={transformItems}
    />
  );
}

classNames · Partial<SortByClassNames>

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.

JavaScript

<SortBy
  // ...
  classNames={{
    root: "MyCustomSortBy",
    select: "MyCustomSortBySelect MyCustomSortBySelect--subclass",
  }}
/>;

...props · React.ComponentProps<'div'>

Any <div> prop to forward to the root element of the widget.

JavaScript

<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. It must be used inside the <InstantSearch> component.

Usage

First, create your React component:

JavaScript

import { useSortBy } from "react-instantsearch";

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

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

Then, render the widget:

JavaScript

<CustomSortBy {...props} />;

Parameters

Hooks accept parameters. You can either pass them manually or forward props from a custom component.

When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders. Use useCallback() for memoization. Arrays and objects are automatically memoized.

items · UseSortByProps['items'] · required

A list of different indices to choose from.

JavaScript

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 · (items: object[], metadata: { results: SearchResults }) => object[]

A function that receives the list of items before they are displayed. It should return a new array with the same structure. Use this to transform, filter, or reorder the items.

The function also has access to the full results data, including all standard response parameters and parameters from the helper, such as disjunctiveFacetsRefinements.

JavaScript

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

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

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

import type { UseSortByProps } from "react-instantsearch";

const transformItems: UseSortByProps["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.

initialIndex · string

The initially selected index.

currentRefinement · string

The currently selected index.

options · SortByItem[]

All the available indices.

TypeScript

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

refine · (value: string) => void

Switches indices and triggers a new search.

canRefine · boolean

Whether the search can be refined.

Example

JavaScript

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>
  );
}

import React from "react";
import { useSortBy, UseSortByProps } from "react-instantsearch";

function SortBy(props: UseSortByProps) {
  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>
  );
}