Filters and refinements

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:

• The ExpandablePanel component to show or hide UI components in a collapsible panel.
• One or more built-in refinements in the sidebar.

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).

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:

• The product listing page
• The RefinementsSidebar file
• Its props.

Usage and props

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

1
2
3
4
<RefinementsSidebar
  // Optional parameters
  dynamicWidgets={boolean} // Whether to use the DynamicWidgets feature.
/>

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.

Code summary

You can customize ExpandablePanel usage in:

• The refinement panel body file
• The ExpandablePanel file
• Its props.

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>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<ExpandablePanel
  // Optional parameters
  header={string} // Panel header text.
  footer={string} // Footer text, added after the widgets.
  attributes={string[]} // The names of the attributes inside the records used to
                        // display the total number of current refinement for this panel.
                        // The prop value should be the same as the one you are
                        // using for the widget(s) contained in the panel.
  isOpened={boolean} // Whether the panel is opened or closed.
  onToggle={function} // Callback function called when the header button is clicked.
                      // This callback function is typically used to toggle the value
                      // of isOpened prop, so the panel is either expanded or collapsed.
  className={string} // Adds a CSS class on the root element.
>
  {children} // The children are one or more React InstantSearch widgets.
</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.

Code summary

You can customize ToggleFilters usage in:

• The refinement bar file
• The ToggleFilters file.

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.

Code summary

You can customize CurrentRefinements usage in:

• The refinement bar file
• The CurrentRefinements file
• Its props

Usage and props

1
<CurrentRefinements />

1
2
3
4
5
<CurrentRefinements
  // Optional parameters
  header={string} // Header text.
  className={string} // Adds a CSS class on the root element.
/>

External packages used

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

Built-in refinements

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

• Category filter: filters on a specific category. All categories are displayed as a hierarchical menu. Implemented with the HierarchicalMenu component
• Brand filter: filters on brands. Implemented with the RefinementList widget
• Price filter: filters by price range. Implemented with the RangeInput component ¹
• Size filter: filters on size. Implemented with the SizeRefinementList widget ¹
• Color filter: filters by color. Implemented with the ColorRefinementList component ¹
• Rating filter: filters on product rating (using a number of stars). Implemented with the RatingSelector component ¹

¹ Custom components that use React InstantSearch connectors.