refinementList

Shows a list of facets for refining search results.

Signature

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

Import

Package manager

import { refinementList } from "instantsearch.js/es/widgets";

const { refinementList } = instantsearch.widgets;
// or directly use instantsearch.widgets.refinementList()

See this widget in action

Preview this widget and its behavior.

About this widget

The refinementList widget is one of the most common widgets in a search UI. With this widget, users 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 includes a “search for facet values” feature, enabling users to search through the values of a specific facet attribute. This helps you find uncommon facet values.

Requirements

The attribute provided to the widget must be in attributes for faceting, either on the dashboard or using the attributesForFaceting parameter 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.

Disappearing facet values

With many facet values, the available options can change depending on the user’s query. The refinement widget displays the most common facet values for a given query.

A user’s chosen value can vanish if they alter the query. This occurs because only the most common facet values are displayed when there are many options. A previously selected value might not appear if it’s uncommon for the new query.

To also show less common values, adjust the maximum number of values with the configure widget. It doesn’t change how many items are shown: the limits you set with limit and showMoreLimit still apply.

JavaScript

search.addWidgets([
  // ...
  configure({
    maxValuesPerFacet: 1000,
  }),
]);

Examples

JavaScript

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

Options

container · string | HTMLElement · required

The CSS Selector of the DOM element inside which the widget is inserted.

string

refinementList({
  // ...
  container: "#refinement-list",
});

refinementList({
  // ...
  container: document.querySelector("#refinement-list"),
});

attribute · string · required

The name of the attribute in the .

To avoid unexpected behavior, you can’t use the same attribute prop in a different type of widget.

JavaScript

refinementList({
  // ...
  attribute: "categories",
});

operator · string · default: "or"

How to apply refinements.

• "or": apply an OR between all selected values.
• "and": apply an AND between all selected values.

Use filters or facet filters for more complex result refinement.

JavaScript

refinementList({
  // ...
  operator: "and",
});

limit · number · default: 10

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.

JavaScript

refinementList({
  //...
  limit: 5,
});

showMore · boolean · default: false

Whether to display a button that expands the number of items.

JavaScript

refinementList({
  // ...
  showMore: true,
});

showMoreLimit · number

The maximum number of displayed items (only used when showMore is set to true).

JavaScript

refinementList({
  //...
  showMoreLimit: 20,
});

showMoreButtonLabel · string

The static accessible name (aria-label) for the Show more and Show less toggle buttons. This option is only used when showMore is true. Use a label that works for both expanded and collapsed states because this value doesn’t change as the button expands or collapses.

JavaScript

refinementList({
  //...
  showMoreButtonLabel: "Show more or show less brands",
});

searchable · boolean · default: false

Whether to add a search input to let users 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.

In some situations, refined facet values might not be present in the data returned by Algolia.

JavaScript

refinementList({
  // ...
  searchable: true,
});

searchablePlaceholder · string · default: "Search..."

The value of the search input’s placeholder.

JavaScript

refinementList({
  // ...
  searchablePlaceholder: "Search our products",
});

searchableIsAlwaysActive · boolean · default: true

When false, disables the search input if there are fewer items to display than the limit option. Otherwise, the search input is always usable.

JavaScript

refinementList({
  // ...
  searchableIsAlwaysActive: false,
});

searchableEscapeFacetValues · boolean · default: true

When true, escapes the facet values that are returned from Algolia. In this case, the surrounding tags are always mark.

JavaScript

refinementList({
  // ...
  searchableEscapeFacetValues: false,
});

sortBy · string[] | function

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.

In some situations, refined facet values might not be present in the data returned by Algolia.

string[]

refinementList({
  // ...
  sortBy: ['count:desc', 'name:asc'],
});

refinementList({
  // ...
  sortBy(a, b) {
    return a.name < b.name ? 1 : -1;
  },
});

templates · object

The templates to use for the widget.

JavaScript

refinementList({
  // ...
  templates: {
    // ...
  },
});

cssClasses · object

The CSS classes you can 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.

JavaScript

refinementList({
  // ...
  cssClasses: {
    root: "MyCustomRefinementList",
    list: [
      "MyCustomRefinementListList",
      "MyCustomRefinementListList--subclass",
    ],
  },
});

transformItems · function

A function that receives the list of items before they are displayed. It should return a new array with the same structure. Use this to transform, filter, or reorder the items.

The function also has access to the full results data, including all standard response parameters and parameters from the helper, such as disjunctiveFacetsRefinements.

JavaScript

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

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

Each template includes an html function, which you can use as a tagged template. This function safely renders templates as HTML strings and works directly in the browser—no build step required. For details, see Templating your UI.

The html function is available in InstantSearch.js version 4.46.0 or later.

item · string | function

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.

function

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>
      `;
    },
  },
});

// String-based templates are deprecated, use functions instead.
refinementList({
  // ...
  templates: {
    item: `
      <a href="{{url}}" style="{{#isRefined}}font-weight: bold{{/isRefined}}">
        <span>{{label}} ({{count}})</span>
      </a>
    `,
  },
});

showMoreText · string | function

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

• isShowingMore: boolean. Whether the list is expanded.

function

refinementList({
  // ...
  templates: {
    showMoreText(data, { html }) {
      return html`<span>${data.isShowingMore ? 'Show less' : 'Show more'}</span>`;
    },
  },
});

// String-based templates are deprecated, use functions instead.
refinementList({
  // ...
  templates: {
    showMoreText: `
      {{#isShowingMore}}
        Show less
      {{/isShowingMore}}
      {{^isShowingMore}}
        Show more
      {{/isShowingMore}}
    `,
  },
});

searchableNoResults · string | function

The template used for when there are no results.

function

refinementList({
  // ...
  templates: {
    searchableNoResults(data, { html }) {
      return html`<span>No results</span>`;
    },
  },
});

// String-based templates are deprecated, use functions instead.
refinementList({
  // ...
  templates: {
    searchableNoResults: "No results",
  },
});

searchableSubmit · string | function

The template used for displaying the submit button.

function

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

// String-based templates are deprecated, use functions instead.
refinementList({
  // ...
  templates: {
    searchableSubmit: "submit",
  },
});

searchableReset · string | function

The template used for displaying the reset button.

function

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

// String-based templates are deprecated, use functions instead.
refinementList({
  // ...
  templates: {
    searchableReset: "reset",
  },
});

searchableLoadingIndicator · string | function

The template used for displaying the loading indicator.

function

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

// String-based templates are deprecated, use functions instead.
refinementList({
  // ...
  templates: {
    searchableLoadingIndicator: "loading",
  },
});

Customize the UI with connectRefinementList

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.

Package manager

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

const { connectRefinementList } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectRefinementList()

Then it’s a 3-step process:

JavaScript

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

JavaScript

const renderRefinementList = (renderOptions, isFirstRender) => {
  const {
    items,
    canRefine,
    refine,
    sendEvent,
    createURL,
    isFromSearch,
    searchForItems,
    hasExhaustiveItems,
    isShowingMore,
    canToggleShowMore,
    toggleShowMore,
    widgetParams,
  } = renderOptions;

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

  // Render the widget
};

Rendering options

items · 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.

JavaScript

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 · boolean · required

Indicates if search state can be refined.

JavaScript

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

  const container = document.querySelector("#refinement-list");
  if (!canRefine) {
    container.innerHTML = "";
    return;
  }
};

refine · function

A function to toggle a refinement.

JavaScript

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 · (eventType, facetValue) => void

The function to send click events. The click event is automatically sent when refine is called. To learn more, see the insights middleware.

• eventType: 'click'
• facetValue: string

JavaScript

// 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 · function

Generates a URL for the corresponding search state.

JavaScript

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 · boolean

Whether the items prop contains facet values from the global search or from the search inside the items.

JavaScript

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 · function

A function to trigger a search inside item 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.

JavaScript

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("");
};

hasExhaustiveItems · boolean

Whether the results are complete.

JavaScript

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

  document.querySelector("#refinement-list").innerHTML = `
    <ul>
      ${items
        .map(
          (item) => `
            <li>
              ${item.label} (${hasExhaustiveItems ? "~" : ""}${item.count})
            </li>`,
        )
        .join("")}
    </ul>
  `;
};

isShowingMore · boolean

Returns true if the menu is displaying all the menu items.

JavaScript

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 · boolean

Returns true if the “Show more” button can be activated (if enough items to display and not already displaying more than limit items).

JavaScript

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 · function

Toggles the number of displayed values between limit and showMoreLimit.

JavaScript

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 · object

All original widget options forwarded to the render function.

JavaScript

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

  widgetParams.container.innerHTML = "...";
};

// ...

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

Create and instantiate the custom widget

First, create your custom widgets using a rendering function. Then, instantiate them with parameters.

There are two kinds of parameters you can pass:

• Instance parameters. Predefined options that configure Algolia’s behavior.
• Custom parameters. Parameters you define to make the widget reusable and adaptable.

Inside the renderFunction, both instance and custom parameters are accessible through connector.widgetParams.

JavaScript

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 · string · required

The name of the attribute in the records.

To avoid unexpected behavior, you can’t use the same attribute prop in a different type of widget.

JavaScript

customRefinementList({
  attribute: "brand",
});

operator · string ('or'|'and') · default: "or"

How to apply refinements.

• "or": apply an OR between all selected values.
• "and": apply an AND between all selected values.

JavaScript

customRefinementList({
  // ...
  operator: "and",
});

limit · number · default: 10

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

JavaScript

customRefinementList({
  // ...
  limit: 5,
});

showMoreLimit · number

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

JavaScript

customRefinementList({
  // ...
  showMoreLimit: 20,
});

escapeFacetValues · boolean · default: true

When activate, escapes the facet values that are returned from Algolia. In this case, the surrounding tags are always mark.

JavaScript

customRefinementList({
  // ...
  escapeFacetValues: false,
});

sortBy · string[] | function

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.

In some situations, refined facet values might not be present in the data returned by Algolia.

string[]

customRefinementList({
  // ...
  sortBy: ['count:desc', 'name:asc'],
});

customRefinementList({
  // ...
  sortBy(a, b) {
    return a.name < b.name ? 1 : -1;
  },
});

transformItems · function

A function that receives the list of items before they are displayed. It should return a new array with the same structure. Use this to transform, filter, or reorder the items.

The function also has access to the full results data, including all standard response parameters and parameters from the helper, such as disjunctiveFacetsRefinements.

JavaScript

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

HTML

<div id="refinement-list"></div>

// 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,
  }),
]);