API Reference / React InstantSearch / CurrentRefinements

CurrentRefinements

Signature 
<CurrentRefinements
  // Optional parameters
  clearsQuery={boolean}
  transformItems={function}
/>
Import
Copy 
1

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

About this widget

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 CurrentRefinements widget displays the list of currently applied refinements.

Examples

Copy 
1
2
3

import { CurrentRefinements } from 'react-instantsearch-dom';

<CurrentRefinements />

Props

clearsQuery
type: boolean
default: false
Optional

Whether the widget should include the query.
Copy 
1

<CurrentRefinements clearsQuery />
transformItems
type: function
default: items => items
Optional

Modifies the items being displayed, for example, to filter or sort them. It takes items as argument and expects them back in return.
Copy 
1
2
3
4
5

<CurrentRefinements
  transformItems={items =>
    items.filter(item => item.attribute !== 'brand')
  }
/>

HTML output

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

<div class="ais-CurrentRefinements">
  <ul class="ais-CurrentRefinements-list">
    <li class="ais-CurrentRefinements-itemt">
      <span class="ais-CurrentRefinements-label">
        Category:
      </span>
      <span class="ais-CurrentRefinements-category">
        <span class="ais-CurrentRefinements-categoryLabel">
          Movies & TV Shows
        </span>
        <button class="ais-CurrentRefinements-delete">✕</button>
      </span>
      <span class="ais-CurrentRefinements-category">
        <span class="ais-CurrentRefinements-categoryLabel">
          Others
        </span>
        <button class="ais-CurrentRefinements-delete">✕</button>
      </span>
    </li>
    <li class="ais-CurrentRefinements-item">
      <span class="ais-CurrentRefinements-label">
        Brand:
      </span>
      <span class="ais-CurrentRefinements-category">
        <span class="ais-CurrentRefinements-categoryLabel">
          Algolia
        </span>
        <button class="ais-CurrentRefinements-delete">✕</button>
      </span>
    </li>
  </ul>
</div>

When there are no refinements to clear:

Copy 
1
2
3
4

<div class="ais-CurrentRefinements">
  <ul class="ais-CurrentRefinements-list">
  </ul>
</div>

Customize the UI with connectCurrentRefinements

If you want to create your own UI of the CurrentRefinements widget or use another UI library, you can use connectors.

Connectors are higher-order components. They encapsulate the logic for a specific kind of widget and they provide a way to interact with the InstantSearch context.

They have an outer component API that we call exposed props, and they provide some other props to the wrapped components which are called the provided props.

This connector is also used to build other widgets: ClearRefinements

It’s a 3-step process:

// 1. Create a React component
const CurrentRefinements = () => {
  // return the DOM output
};

// 2. Connect the component using the connector
const CustomCurrentRefinements = connectCurrentRefinements(CurrentRefinements);

// 3. Use your connected widget
<CustomCurrentRefinements />

See code examples

Create a React component

const CurrentRefinements = ({
  object[] items,
  function refine,
  function createURL,
}) => {
  // return the DOM output
};

Provided Props

items
type: object[]

The currently applied filters. It’s an array of objects with :

  • label: string: the label for the value.
  • attribute: string: the name of the attribute.
  • currentRefinement: any: the raw value of the refinement (depends on the widget).
  • items: object[]: a list of elements in case the refinement accept multiple values (e.g., RefinementList).
  • value: function: the value to provide to therefine function to clear the refinement.

The value contains the argument to provide to the refine function for removing the refinement, label is for the display. When there are several refinements for the same attribute name, you get a nested items array that contains a label and a value used to remove a single filter with refine. The attribute and currentRefinement properties are metadata containing the raw values.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

const CurrentRefinements = ({ items }) => (
  <ul>
    {items.map(item => (
      <li key={item.label}>
        {item.items ? (
          <React.Fragment>
            {item.label}
            <ul>
              {item.items.map(nested => (
                <li key={nested.label}>
                  <a href="#">{nested.label}</a>
                </li>
              ))}
            </ul>
          </React.Fragment>
        ) : (
          <a href="#">{item.label}</a>
        )}
      </li>
    ))}
  </ul>
);
refine
type: function

Removes a currently applied filter.
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

const CurrentRefinements = ({ items, refine }) => (
  <ul>
    {items.map(item => (
      <li key={item.label}>
        {item.items ? (
          <React.Fragment>
            {item.label}
            <ul>
              {item.items.map(nested => (
                <li key={nested.label}>
                  <a
                    href="#"
                    onClick={event => {
                      event.preventDefault();
                      refine(nested.value);
                    }}
                  >
                    {nested.label}
                  </a>
                </li>
              ))}
            </ul>
          </React.Fragment>
        ) : (
          <a
            href="#"
            onClick={event => {
              event.preventDefault();
              refine(item.value);
            }}
          >
            {item.label}
          </a>
        )}
      </li>
    ))}
  </ul>
);
createURL
type: function

Generates a URL for the corresponding search state.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

const CurrentRefinements = ({ items, createURL }) => (
  <ul>
    {items.map(item => (
      <li key={item.label}>
        {item.items ? (
          <React.Fragment>
            {item.label}
            <ul>
              {item.items.map(nested => (
                <li key={nested.label}>
                  <a href={createURL(nested.value)}>{nested.label}</a>
                </li>
              ))}
            </ul>
          </React.Fragment>
        ) : (
          <a href={createURL(item.value)}>{item.label}</a>
        )}
      </li>
    ))}
  </ul>
);

Create and instantiate your connected widget

const CustomCurrentRefinements = connectCurrentRefinements(CurrentRefinements);

<CustomCurrentRefinements
  // optional parameters
  clearsQuery={boolean}
  transformItems={function}
/>

Exposed Props

clearsQuery
type: boolean
Optional

Whether the widget should include the query.
Copy 
1

<CustomCurrentRefinements clearsQuery />
transformItems
type: function
Optional

Modifies the items being displayed, for example, to filter or sort them. It takes items as argument and expects them back in return.
Copy 
1
2
3
4
5

<CustomCurrentRefinements
  transformItems={items =>
    items.filter(item => item.attribute !== 'brand')
  }
/>

Full example

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

import { connectCurrentRefinements } from 'react-instantsearch-dom';

const CurrentRefinements = ({ items, refine, createURL }) => (
  <ul>
    {items.map(item => (
      <li key={item.label}>
        {item.items ? (
          <React.Fragment>
            {item.label}
            <ul>
              {item.items.map(nested => (
                <li key={nested.label}>
                  <a
                    href={createURL(nested.value)}
                    onClick={event => {
                      event.preventDefault();
                      refine(nested.value);
                    }}
                  >
                    {nested.label}
                  </a>
                </li>
              ))}
            </ul>
          </React.Fragment>
        ) : (
          <a
            href={createURL(item.value)}
            onClick={event => {
              event.preventDefault();
              refine(item.value);
            }}
          >
            {item.label}
          </a>
        )}
      </li>
    ))}
  </ul>
);

const CustomCurrentRefinements = connectCurrentRefinements(CurrentRefinements);
Did you find this page helpful?
React InstantSearch v6