Guides / Building Search UI / Ecommerce ui template / Components / Product listing page filter and nav

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 Filters and refinements components allow users to filter results with a sidebar. The sidebar is responsive and can be shown or hidden on desktop to save space (using the ToggleFilters component).

You can also use:

Refinements sidebar

The RefinementsSidebar component provides a way to filter the results by facet. Each facet is displayed in an expandable panel (collapsed by default). You can expand or collapse all the panels simultaneously to see all the facet values.

The component is fully responsive, adapting to mobile devices by displaying above the results (compare the Mobile and Desktop versions, below).

The RefinementsSidebar component on desktop

It uses DynamicWidgets to match and reorder the widgets based on the corresponding settings of the index. You can change this behavior with a Rule.

Code summary

RefinementsSidebar is only displayed when the refinementsLayout configuration value is sidebar or when the user is on a mobile device.

You can customize RefinementsSidebar in:

Usage and props

1
2
3
<RefinementsSidebar
  dynamicWidgets={true}
/>

Expandable panel

The ExpandablePanel allows you to show or hide UI components in a collapsible panel. The panel can be expanded or collapsed depending on a provided prop. It also displays the total number of current refinements for the contained widgets.

The ExpandablePanel component on desktop

Code summary

You can customize ExpandablePanel usage in:

The ExpandablePanel is a React controlled component..

Usage and props

1
2
3
4
5
6
7
8
9
10
11
12
13
const attributes = [
  'hierarchicalCategories.lvl0',
  'hierarchicalCategories.lvl1',
  'hierarchicalCategories.lvl2'
]

<ExpandablePanel
  header="Categories"
  isOpened={true}
  attributes={attributes}
>
  <HierarchicalMenu attributes={attributes} />
</ExpandablePanel>

Toggle filters

The ToggleFilters component allows you to show or hide the RefinementsSidebar component on desktop screens. This component isn’t used on mobile devices, and RefinementsSidebar is hidden by default.

Toggle filters component

Code summary

You can customize ToggleFilters usage in:

1
<ToggleFilters />

No props are needed for this component.

Current refinements

The CurrentRefinements component displays the list of currently applied refinements as buttons. When clicked, that refinement is cleared. The “Clear all” button lets you clear all refinements simultaneously.

The CurrentRefinements component on desktop

Code summary

You can customize CurrentRefinements usage in:

Usage and props

1
<CurrentRefinements />

External packages used

The “Filters and refinements” components depend on these npm packages:

Package Description Used by
classnames A utility for conditionally joining CSS class names RefinementsSidebar, CurrentRefinements
jotai The state management library (written in TypeScript) RefinementsSidebar, ToggleFilters, CurrentRefinements
@material-design-icons/svg Google’s Material Design icons RefinementsSidebar, ToggleFilters
framer-motion Animates the expanded/collapsed states of the component ExpandablePanel, CurrentRefinements
react-fact-compare Compares the current and next props provided by the connectCurrentRefinements connector and decides whether to trigger a re-render CurrentRefinements
react-instantsearch-dom Provides built-in refinements that you can use to add filters to the sidebar (see below). It also provides the connectCurrentRefinements connector to show the total number of current refinements ExpandablePanel, CurrentRefinements

Built-in refinements

The Ecommerce UI template has several built-in refinements that you can use in the sidebar:

1 Custom components that use React InstantSearch connectors.

Did you find this page helpful?
React InstantSearch v6