API Reference / React InstantSearch Widgets / CurrentRefinements

CurrentRefinements

A
Widget signature 
<CurrentRefinements
  // Optional parameters
  clearsQuery={boolean}
  transformItems={function}
/>
See code examples
See Live example

About this widget # A

The CurrentRefinements widget displays the list of currently applied refinements.

Examples # A

Copy 
1
2
3

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

<CurrentRefinements />

Props # A

clearsQuery #
type: boolean
default: false
Optional

Whether or not 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# A

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 - connectCurrentRefinements# A

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 or not 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