API Reference / React InstantSearch Hooks / <CurrentRefinements>

<CurrentRefinements>

A
Signature 
<CurrentRefinements
  // Optional props
  includedAttributes={string[]}
  excludedAttributes={string[]}
  transformItems={function}
  classNames={object}
  ...props={ComponentProps<'div'>}
/>
Import
Copy 
1

import { CurrentRefinements } from 'react-instantsearch-hooks-web';
See code examples
See live example

About this widget # A

<CurrentRefinements> is a widget that lets you display the list of active refinements in the search.

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

Examples # A

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

import React from 'react';
import algoliasearch from 'algoliasearch/lite';
import { InstantSearch, CurrentRefinements } from 'react-instantsearch-hooks-web';

const searchClient = algoliasearch('AJ0P3S7DWQ', '90dfaaf5755e694f341fe68f6e41a6d4');

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <CurrentRefinements />
    </InstantSearch>
  );
}

Props # A

includedAttributes #
type: string[]
default: []

The attributes to include (all by default). This parameter can’t be used with excludedAttributes.

In the example below, only the categories attribute is included.
Copy 
1

<CurrentRefinements includedAttributes={['categories']} />
excludedAttributes #
type: string[]
default: ['query']

The attributes to exclude from the widget. This parameter can’t be used with includedAttributes.

In the example below, the brand attribute is excluded.
Copy 
1

<CurrentRefinements excludedAttributes={['brand']} />
transformItems #
type: (items: object[], metadata: { results: SearchResults }) => object[]
default: items => items

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

const transformItems = (items) => {
  return items.filter((item) => item.attribute !== 'brand');
};

function Search() {
  return (
    <CurrentRefinements
      // ...
      transformItems={transformItems}
    />
  );
}
classNames #
type: Partial<CurrentRefinementsClassNames>
Optional

CSS classes to pass to the widget’s elements. This is useful to style widgets with class-based CSS frameworks like Bootstrap or Tailwind CSS.

  • root: The root element of the widget.
  • noRefinementRoot: The root element when there are no refinements.
  • list: The list element.
  • noRefinementList: The list element when there are no refinements.
  • item: Each refinement element.
  • label: The label of each refinement.
  • category: The container of each refinement’s value.
  • categoryLabel: The text element of each refinement’s value.
  • delete: The delete button of each refinement.
Copy 
1
2
3
4
5
6

<CurrentRefinements
  classNames={{
    root: 'MyCustomCurrentRefinements',
    list: 'MyCustomCurrentRefinementsList MyCustomCurrentRefinementsList--subclass',
  }}
/>
...props #
type: React.ComponentProps<'div'>
Optional

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

<CurrentRefinements
  className="MyCustomCurrentRefinements"
  title="My custom title"
/>

Hook# A

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

The useCurrentRefinements() Hook accepts parameters and returns APIs.

See code examples

Usage#

First, create your React component:

import { useCurrentRefinements } from 'react-instantsearch-hooks-web';

function CustomCurrentRefinements(props) {
  const { items, canRefine, refine } = useCurrentRefinements(props);

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

Then, render the widget:

<CustomCurrentRefinements {...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.

includedAttributes #
type: string[]
default: []

The attributes to include (all by default). This parameter can’t be used with excludedAttributes.

In the example below, only the categories attribute is included.
Copy 
1
2
3

const currentRefinementsApi = useCurrentRefinements({
  includedAttributes: ['categories'],
});
excludedAttributes #
type: string[]
default: ['query']

The attributes to exclude from the widget. This parameter can’t be used with includedAttributes.

In the example below, the brand attribute is excluded.
Copy 
1
2
3

const currentRefinementsApi = useCurrentRefinements({
  excludedAttributes: ['brand'],
});
transformItems #
type: (items: object[], metadata: { results: SearchResults }) => object[]
default: items => items

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

const transformItems = (items) => {
  return items.filter((item) => item.attribute !== 'brand');
};

function CurrentRefinements() {
  const currentRefinementsApi = useCurrentRefinements({
    // ...
    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.

items #
type: CurrentRefinementsItem[]

All the currently refined items grouped by attribute.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

type CurrentRefinementsItem = {
  /**
   * The index name.
   */
  indexName: string;
  /**
   * The attribute on which the refinement is applied.
   */
  attribute: string;
  /**
   * The textual representation of this attribute.
   */
  label: string;
  /**
   * Currently applied refinements.
   */
  refinements: CurrentRefinementsRefinement[];
  /**
   * Removes the given refinement and triggers a new search.
   */
  refine(refinement: CurrentRefinementsRefinement): void;
};

type CurrentRefinementsRefinement = {
  /**
   * The attribute on which the refinement is applied.
   */
  attribute: string;
  /**
   * The type of the refinement.
   *
   * It can be one of those: 'facet'|'exclude'|'disjunctive'|'hierarchical'|'numeric'|'query'|'tag'.
   */
  type: string;
  /**
   * The raw value of the refinement.
   */
  value: string | number;
  /**
   * The label of the refinement to display.
   */
  label: string;
  /**
   * The value of the operator (only if applicable).
   */
  operator?: string;
  /**
   * The number of found items (only if applicable).
   */
  count?: number;
  /**
   * Whether the count is exhaustive (only if applicable).
   */
  exhaustive?: boolean;
};
canRefine #
type: boolean

Whether the search state can be refined.
refine #
type: (value: CurrentRefinementsItem) => void

Clears a single refinement and triggers a new search.

Example#

Copy 
1
2
3
4
5
6
7
8

import React from 'react';
import { useCurrentRefinements } from 'react-instantsearch-hooks-web';

function CustomCurrentRefinements(props) {
  const { items, refine } = useCurrentRefinements(props);

  return <>{/* Your JSX */}</>;
}
Did you find this page helpful?
React InstantSearch Hooks v6