API Reference / InstantSearch.js / refinementList

refinementList

A
Signature 
refinementList({
  container: string|HTMLElement,
  attribute: string,
  // Optional parameters
  operator: string,
  limit: number,
  showMore: boolean,
  showMoreLimit: number,
  searchable: boolean,
  searchablePlaceholder: string,
  searchableIsAlwaysActive: boolean,
  searchableEscapeFacetValues: boolean,
  sortBy: string[]|function,
  templates: object,
  cssClasses: object,
  transformItems: function,
});
Import
Copy 
1

import { refinementList } from 'instantsearch.js/es/widgets';
See code examples
See live example

About this widget # A

The refinementList widget is one of the most common widget you can find in a search UI. With this widget, the user can filter the dataset based on facets.

The widget only displays the most relevant facet values for the current search context. The sort option only affects the facets that are returned by the engine, not which facets are returned.

This widget also implements search for facet values, which is a mini search inside the values of the facets. This makes it easy to deal with uncommon facet values.

Requirements#

The attribute provided to the widget must be in attributes for faceting, either on the dashboard or using attributesForFaceting with the API.

If you are using the searchable prop, you also need to make the attribute searchable using the dashboard or using the searchable modifier of attributesForFaceting with the API.

Examples # A

Copy 
1
2
3
4

refinementList({
  container: '#refinement-list',
  attribute: 'brand',
});

Options # A

container #
type: string|HTMLElement
Required

The CSS Selector of the DOM element inside which the widget is inserted.
Copy 
1
2
3
4

refinementList({
  // ...
  container: '#refinement-list',
});
attribute #
type: string
Required

The name of the attribute in the records.
Copy 
1
2
3
4

refinementList({
  // ...
  attribute: 'categories',
});
operator #
type: string
default: "or"
Optional

How to apply refinements.

  • "or": apply an OR between all selected values.
  • "and": apply an AND between all selected values.
Copy 
1
2
3
4

refinementList({
  // ...
  operator: 'and',
});
limit #
type: number
default: 10
Optional

How many facet values to retrieve. When you enable the showMore feature, this is the number of facet values to display before clicking the “Show more” button.
Copy 
1
2
3
4

refinementList({
  //...
  limit: 5,
});
showMore #
type: boolean
default: false
Optional

Whether to display a button that expands the number of items.
Copy 
1
2
3
4

refinementList({
  // ...
  showMore: true,
});
showMoreLimit #
type: number
Optional

The maximum number of displayed items (only used when showMore is set to true).
Copy 
1
2
3
4

refinementList({
  //...
  showMoreLimit: 20,
});
searchable #
type: boolean
default: false
Optional

Whether to add a search input to let the user search for more facet values.

To make this feature work, you need to make the attribute searchable using the dashboard or using the searchable modifier of attributesForFaceting with the API.
Copy 
1
2
3
4

refinementList({
  // ...
  searchable: true,
});
searchablePlaceholder #
type: string
default: Search...
Optional

The value of the search input’s placeholder.
Copy 
1
2
3
4

refinementList({
  // ...
  searchablePlaceholder: 'Search our products',
});
searchableIsAlwaysActive #
type: boolean
default: true
Optional

When false, disables the search input if there are less items to display than the limit option. Otherwise, the search input is always usable.
Copy 
1
2
3
4

refinementList({
  // ...
  searchableIsAlwaysActive: false,
});
searchableEscapeFacetValues #
type: boolean
default: true
Optional

When true, escapes the facet values that are returned from Algolia. In this case, the sourrounding tags are always mark.
Copy 
1
2
3
4

refinementList({
  // ...
  searchableEscapeFacetValues: false,
});
sortBy #
type: string[]|function
default: Uses facetOrdering if set, ["isRefined","count:desc","name:asc"]

How to sort refinements. Must be one or more of the following strings:

  • "count" (same as "count:desc")
  • "count:asc"
  • "count:desc"
  • "name" (same as "name:asc")
  • "name:asc"
  • "name:desc"
  • "isRefined" (same as "isRefined:asc")
  • "isRefined:asc"
  • "isRefined:desc"

It’s also possible to give a function, which receives items two by two, like JavaScript’s Array.sort.

If facetOrdering is set for this facet in renderingContent, and no value for sortBy is passed to this widget, facetOrdering is used, and the default order as a fallback.
Copy 
1
2
3
4

refinementList({
  // ...
  sortBy: ['count:desc', 'name:asc'],
});
templates #
type: object
Optional

The templates to use for the widget.
Copy 
1
2
3
4
5
6

refinementList({
  // ...
  templates: {
    // ...
  },
});
cssClasses #
type: object

The CSS classes to override.

  • root: the root element of the widget.
  • noRefinementRoot: the root element if there are no refinements.
  • noResults: the root element if there are no results.
  • list: the list of results.
  • item: the list items. They contain the link and separator.
  • selectedItem: each selected item in the list.
  • label: each label element (when using the default template).
  • checkbox: each checkbox element (when using the default template).
  • labelText: each label text element.
  • showMore: the “Show more” element.
  • disabledShowMore: the disabled “Show more” element.
  • count: each count element (when using the default template).
  • searchableRoot: the root element of the search box.
  • searchableForm: the form element of the search box.
  • searchableInput: the input element of the search box.
  • searchableSubmit: the reset button element of the search box.
  • searchableSubmitIcon: the reset button icon of the search box.
  • searchableReset: the loading indicator element of the search box.
  • searchableResetIcon: the loading indicator icon of the search box.
  • searchableLoadingIndicator: the submit button element of the search box.
  • searchableLoadingIcon: the submit button icon of the search box.
Copy 
1
2
3
4
5
6
7
8
9
10

refinementList({
  // ...
  cssClasses: {
    root: 'MyCustomRefinementList',
    list: [
      'MyCustomRefinementListList',
      'MyCustomRefinementListList--subclass',
    ],
  },
});
transformItems #
type: function
Optional

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
13
14
15
16
17
18
19

refinementList({
  // ...
  transformItems(items) {
    return items.map(item => ({
      ...item,
      highlighted: item.highlighted.toUpperCase(),
    }));
  },
});

/* or, combined with results */
refinementList({
  // ...
  transformItems(items, { results }) {
    return results.page === 0
      ? items.slice(0, 5)
      : items;
  },
});

Templates # A

You can customize parts of the widget’s UI using the Templates API.

Every template provides an html function you can use as a tagged template. Using html lets you safely provide templates as an HTML string. It works directly in the browser without a build step. See Templating your UI for more information.

The html function is available starting from v4.46.0.

item #
type: string|function
Optional

The template used for an item. It exposes:

  • count: the number of occurrences of the facet in the result set.
  • isRefined: returns true if the value is selected.
  • label: the label to display.
  • value: the value used for refining.
  • highlighted: the highlighted label (when using search for facet values). This value is displayed in the default template.
  • url: the URL with the selected refinement.
  • cssClasses: an object containing all the computed classes for the item.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

refinementList({
  // ...
  templates: {
    item(item, { html }) {
      const { url, label, count, isRefined } = item;

      return html`
        <a href="${url}" style="${isRefined ? 'font-weight: bold' : ''}">
          <span>${label} (${count})</span>
        </a>
      `;
    },
  },
});
showMoreText #
type: string|function
Optional

The template for the “Show more” button text. It exposes:

  • isShowingMore: boolean: whether the list is expanded.
Copy 
1
2
3
4
5
6
7
8

refinementList({
  // ...
  templates: {
    showMoreText(data, { html }) {
      return html`<span>${data.isShowingMore ? 'Show less' : 'Show more'}</span>`;
    },
  },
});
searchableNoResults #
type: string|function
Optional

The template used for when there are no results.
Copy 
1
2
3
4
5
6
7
8

refinementList({
  // ...
  templates: {
    searchableNoResults(data, { html }) {
      return html`<span>No results</span>`;
    },
  },
});
searchableSubmit #
type: string|function
Optional

The template used for displaying the submit button.
Copy 
1
2
3
4
5
6
7
8

refinementList({
  // ...
  templates: {
    searchableSubmit(data, { html }) {
      return html`<span>submit</span>`;
    },
  },
});
searchableReset #
type: string|function
Optional

The template used for displaying the reset button.
Copy 
1
2
3
4
5
6
7
8

refinementList({
  // ...
  templates: {
    searchableReset(data, { html }) {
      return html`<span>reset</span>`;
    },
  },
});
searchableLoadingIndicator #
type: string|function
Optional

The template used for displaying the loading indicator.
Copy 
1
2
3
4
5
6
7
8

refinementList({
  // ...
  templates: {
    searchableLoadingIndicator(data, { html }) {
      return html`<span>loading</span>`;
    },
  },
});

Customize the UI with connectRefinementList# A

If you want to create your own UI of the refinementList widget, you can use connectors.

To use connectRefinementList, you can import it with the declaration relevant to how you installed InstantSearch.js.

Copy 
1

import { connectRefinementList } from 'instantsearch.js/es/connectors';

Then it’s a 3-step process:

// 1. Create a render function
const renderRefinementList = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customRefinementList = connectRefinementList(
  renderRefinementList
);

// 3. Instantiate
search.addWidgets([
  customRefinementList({
    // instance params
  })
]);

See code examples

Create a render function#

This rendering function is called before the first search (init lifecycle step) and each time results come back from Algolia (render lifecycle step).

const renderRefinementList = (renderOptions, isFirstRender) => {
  const {
    object[] items,
    boolean canRefine,
    function refine,
    function sendEvent,
    function createURL,
    boolean isFromSearch,
    function searchForItems,
    boolean isShowingMore,
    boolean canToggleShowMore,
    function toggleShowMore,
    object widgetParams,
  } = renderOptions;

  if (isFirstRender) {
    // Do some initial rendering and bind events
  }

  // Render the widget
}

Rendering options #

items #
type: object[]

The list of refinement values returned from the Algolia API.

Each object has the following properties:

  • value: string: the value of the item.
  • label: string: the label of the item.
  • count: number: the number of results that match the item.
  • isRefined: boolean: indicates if the refinement is applied.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

const renderRefinementList = (renderOptions, isFirstRender) => {
  const { items } = renderOptions;

  document.querySelector('#refinement-list').innerHTML = `
    <ul>
      ${items
        .map(
          item => `
            <li>
              <a href="#">
                ${item.label} (${item.count})
              </a>
            </li>`
        )
        .join('')}
    </ul>
  `;
};
canRefine #
type: boolean
Required

Indicates if search state can be refined.
Copy 
1
2
3
4
5
6
7
8
9

const renderRefinementList = (renderOptions, isFirstRender) => {
  const { items, canRefine, refine } = renderOptions;

  const container = document.querySelector('#refinement-list');
  if (!canRefine) {
    container.innerHTML = '';
    return;
  }
};
refine #
type: function

A function to toggle a refinement.
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

const renderRefinementList = (renderOptions, isFirstRender) => {
  const { items, refine } = renderOptions;

  const container = document.querySelector('#refinement-list');

  container.innerHTML = `
    <ul>
      ${items
        .map(
          item => `
            <li>
              <a
                href="#"
                data-value="${item.value}"
                style="font-weight: ${item.isRefined ? 'bold' : ''}"
              >
                ${item.label} (${item.count})
              </a>
            </li>`
        )
        .join('')}
    </ul>
  `;

  [...container.querySelectorAll('a')].forEach(element => {
    element.addEventListener('click', event => {
      event.preventDefault();
      refine(event.currentTarget.dataset.value);
    });
  });
};
sendEvent #
type: (eventType, facetValue) => void

The function to send click events. The click event is automatically sent when refine is called. You can learn more about the insights middleware.

  • eventType: 'click'
  • facetValue: string
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// For example,
sendEvent('click', 'Apple');

/*
  A payload like the following will be sent to the `insights` middleware.
  {
    eventType: 'click',
    insightsMethod: 'clickedFilters',
    payload: {
      eventName: 'Filter Applied',
      filters: ['brand:"Apple"'],
      index: '<index-name>',
    },
    widgetType: 'ais.refinementList',
  }
*/
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

const renderRefinementList = (renderOptions, isFirstRender) => {
  const { items, createURL } = renderOptions;

  document.querySelector('#refinement-list').innerHTML = `
    <ul>
      ${items
        .map(
          item => `
            <li>
              <a
                href="${createURL(item.value)}"
                style="font-weight: ${item.isRefined ? 'bold' : ''}"
              >
                ${item.label} (${item.count})
              </a>
            </li>`
        )
        .join('')}
    </ul>
  `;
};
isFromSearch #
type: boolean

Whether the items prop contains facet values from the global search or from the search inside the items.
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

const renderRefinementList = (renderOptions, isFirstRender) => {
  const { items, isFromSearch, refine, searchForItems } = renderOptions;

  const container = document.querySelector('#refinement-list');

  if (isFirstRender) {
    const ul = document.createElement('ul');
    const input = document.createElement('input');

    input.addEventListener('input', event => {
      searchForItems(event.currentTarget.value);
    });

    container.appendChild(input);
    container.appendChild(ul);
  }

  const input = container.querySelector('input');

  if (!isFromSearch && input.value) {
    input.value = '';
  }

  container.querySelector('ul').innerHTML = items
    .map(
      item => `
        <li>
          <a
            href="#"
            data-value="${item.value}"
            style="font-weight: ${item.isRefined ? 'bold' : ''}"
          >
            ${item.label} (${item.count})
          </a>
        </li>
      `
    )
    .join('');

  [...container.querySelectorAll('a')].forEach(element => {
    element.addEventListener('click', event => {
      event.preventDefault();
      refine(event.currentTarget.dataset.value);
    });
  });
};
searchForItems #
type: function

A function to trigger a search inside items values.

To make this feature work, you need to make the attribute searchable using the dashboard or using the searchable modifier of attributesForFaceting with the API.
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

const renderRefinementList = (renderOptions, isFirstRender) => {
  const { items, searchForItems } = renderOptions;

  const container = document.querySelector('#refinement-list');

  if (isFirstRender) {
    const ul = document.createElement('ul');
    const input = document.createElement('input');

    input.addEventListener('input', event => {
      searchForItems(event.currentTarget.value);
    });

    container.appendChild(input);
    container.appendChild(ul);
  }

  container.querySelector('ul').innerHTML = items
    .map(
      item => `
        <li>
          <a href="#">
            ${item.label} (${item.count})
          </a>
        </li>
      `
    )
    .join('');
};
isShowingMore #
type: boolean

Returns true if the menu is displaying all the menu items.
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

const renderRefinementList = (renderOptions, isFirstRender) => {
  const { items, isShowingMore, toggleShowMore } = renderOptions;

  const container = document.querySelector('#refinement-list');

  if (isFirstRender) {
    const ul = document.createElement('ul');
    const button = document.createElement('button');
    button.textContent = 'Show more';

    button.addEventListener('click', () => {
      toggleShowMore();
    });

    container.appendChild(ul);
    container.appendChild(button);
  }

  container.querySelector('ul').innerHTML = items
    .map(
      item => `
        <li>
          <a href="#">
            ${item.label} (${item.count})
          </a>
        </li>
      `
    )
    .join('');

  container.querySelector('button').textContent = isShowingMore
    ? 'Show less'
    : 'Show more';
};
canToggleShowMore #
type: boolean

Returns true if the “Show more” button can be activated (if enough items to display and not already displaying more than limit items).
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

const renderRefinementList = (renderOptions, isFirstRender) => {
  const { items, canToggleShowMore, toggleShowMore } = renderOptions;

  const container = document.querySelector('#refinement-list');

  if (isFirstRender) {
    const ul = document.createElement('ul');
    const button = document.createElement('button');
    button.textContent = 'Show more';

    button.addEventListener('click', () => {
      toggleShowMore();
    });

    container.appendChild(ul);
    container.appendChild(button);
  }

  container.querySelector('ul').innerHTML = items
    .map(
      item => `
        <li>
          <a href="#">
            ${item.label} (${item.count})
          </a>
        </li>
      `
    )
    .join('');

  container.querySelector('button').disabled = !canToggleShowMore;
};
toggleShowMore #
type: function

Toggles the number of displayed values between limit and showMoreLimit.
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

const renderRefinementList = (renderOptions, isFirstRender) => {
  const { items, toggleShowMore } = renderOptions;

  const container = document.querySelector('#refinement-list');

  if (isFirstRender) {
    const ul = document.createElement('ul');
    const button = document.createElement('button');
    button.textContent = 'Show more';

    button.addEventListener('click', () => {
      toggleShowMore();
    });

    container.appendChild(ul);
    container.appendChild(button);
  }

  container.querySelector('ul').innerHTML = items
    .map(
      item => `
        <li>
          <a href="#">
            ${item.label} (${item.count})
          </a>
        </li>
      `
    )
    .join('');
};
widgetParams #
type: object

All original widget options forwarded to the render function.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

const renderRefinementList = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

  widgetParams.container.innerHTML = '...';
};

// ...

search.addWidgets([
  customRefinementList({
    // ...
    container: document.querySelector('#refinement-list'),
  })
]);

Create and instantiate the custom widget#

We first create custom widgets from our rendering function, then we instantiate them. When doing that, there are two types of parameters you can give:

  • Instance parameters: they are predefined parameters that you can use to configure the behavior of Algolia.
  • Your own parameters: to make the custom widget generic.

Both instance and custom parameters are available in connector.widgetParams, inside the renderFunction.

const customRefinementList = connectRefinementList(
  renderRefinementList
);

search.addWidgets([
  customRefinementList({
    attribute: string,
    // Optional parameters
    operator: string,
    limit: number,
    showMoreLimit: number,
    escapeFacetValues: boolean,
    sortBy: string[]|function,
    transformItems: function,
  })
]);

Instance options #

attribute #
type: string
Required

The name of the attribute in the records.
Copy 
1
2
3

customRefinementList({
  attribute: 'brand',
});
operator #
type: string ("or"|"and")
default: "or"
Optional

How to apply refinements.

  • "or": apply an OR between all selected values.
  • "and": apply an AND between all selected values.
Copy 
1
2
3
4

customRefinementList({
  // ...
  operator: 'and',
});
limit #
type: number
default: 10
Optional

How many facet values to retrieve. When isShowingMore is false, this is the number of facet values displayed before clicking the “Show more” button.
Copy 
1
2
3
4

customRefinementList({
  // ...
  limit: 5,
});
showMoreLimit #
type: number
Optional

The maximum number of items to display if the widget is showing more items. Needs to be bigger than the limit parameter.
Copy 
1
2
3
4

customRefinementList({
  // ...
  showMoreLimit: 20,
});
escapeFacetValues #
type: boolean
default: true
Optional

When activate, escapes the facet values that are returned from Algolia. In this case, the sourrounding tags are always mark.
Copy 
1
2
3
4

customRefinementList({
  // ...
  escapeFacetValues: false,
});
sortBy #
type: string[]|function
default: Uses facetOrdering if set, ["isRefined","count:desc","name:asc"]
Optional

How to sort refinements. Must be one or more of the following strings:

  • "count:asc"
  • "count:desc"
  • "name:asc"
  • "name:desc"
  • "isRefined"

It’s also possible to give a function, which receives items two by two, like JavaScript’s Array.sort.

If facetOrdering is set for this facet in renderingContent, and no value for sortBy is passed to this widget, facetOrdering is used, and the default order as a fallback.
Copy 
1
2
3
4

customRefinementList({
  // ...
  sortBy: ['count:desc', 'name:asc'],
});
transformItems #
type: function
Optional

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
13
14
15
16
17
18
19

customRefinementList({
  // ...
  transformItems(items) {
    return items.map(item => ({
      ...item,
      label: item.label.toUpperCase(),
    }));
  },
});

/* or, combined with results */
customRefinementList({
  // ...
  transformItems(items, { results }) {
    return results.page === 0
      ? items.slice(0, 5)
      : items;
  },
});

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
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

// 1. Create a render function
const renderRefinementList = (renderOptions, isFirstRender) => {
  const {
    items,
    isFromSearch,
    refine,
    createURL,
    isShowingMore,
    canToggleShowMore,
    searchForItems,
    toggleShowMore,
    widgetParams,
  } = renderOptions;

  if (isFirstRender) {
    const input = document.createElement('input');
    const ul = document.createElement('ul');
    const button = document.createElement('button');
    button.textContent = 'Show more';

    input.addEventListener('input', event => {
      searchForItems(event.currentTarget.value);
    });

    button.addEventListener('click', () => {
      toggleShowMore();
    });

    widgetParams.container.appendChild(input);
    widgetParams.container.appendChild(ul);
    widgetParams.container.appendChild(button);
  }

  const input = widgetParams.container.querySelector('input');

  if (!isFromSearch && input.value) {
    input.value = '';
  }

  widgetParams.container.querySelector('ul').innerHTML = items
    .map(
      item => `
        <li>
          <a
            href="${createURL(item.value)}"
            data-value="${item.value}"
            style="font-weight: ${item.isRefined ? 'bold' : ''}"
          >
            ${item.label} (${item.count})
          </a>
        </li>
      `
    )
    .join('');

  [...widgetParams.container.querySelectorAll('a')].forEach(element => {
    element.addEventListener('click', event => {
      event.preventDefault();
      refine(event.currentTarget.dataset.value);
    });
  });

  const button = widgetParams.container.querySelector('button');

  button.disabled = !canToggleShowMore;
  button.textContent = isShowingMore ? 'Show less' : 'Show more';
};

// 2. Create the custom widget
const customRefinementList = connectRefinementList(
  renderRefinementList
);

// 3. Instantiate
search.addWidgets([
  customRefinementList({
    container: document.querySelector('#refinement-list'),
    attribute: 'brand',
    showMoreLimit: 20,
  })
]);
Did you find this page helpful?
InstantSearch.js v4