> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# currentRefinements

> Shows applied refinements and lets users remove them.

```ts Signature theme={"system"}
currentRefinements({
  container: string | HTMLElement,
  // Optional parameters
  includedAttributes?: string[],
  excludedAttributes?: string[],
  cssClasses?: object,
  transformItems?: function,
});
```

## Import

<CodeGroup>
  ```js Package manager theme={"system"}
  import { currentRefinements } from "instantsearch.js/es/widgets";
  ```

  ```js CDN theme={"system"}
  const { currentRefinements } = instantsearch.widgets;
  // or directly use instantsearch.widgets.currentRefinements()
  ```
</CodeGroup>

<Card title="See this widget in action" icon="monitor-play" href="https://instantsearchjs.netlify.app/stories/js/?path=/story/refinements-currentrefinements--default" horizontal>
  Preview this widget and its behavior.
</Card>

## About this widget

The `currentRefinements` widget displays a list of [refinements](/doc/api-reference/widgets/refinement-list/js) applied to the search.

## Examples

```js JavaScript icon=code theme={"system"}
currentRefinements({
  container: "#current-refinements",
});
```

## Options

<ParamField body="container" type="string | HTMLElement" required>
  The CSS Selector or `HTMLElement` to insert the widget into.

  <CodeGroup>
    ```js string theme={"system"}
    currentRefinements({
      container: "#current-refinements",
    });
    ```

    ```js HTMLElement theme={"system"}
    currentRefinements({
      container: document.querySelector("#current-refinements"),
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="includedAttributes" type="string[]" default="[]">
  The attributes to include in the widget (all by default).
  Cannot be used with [`excludedAttributes`](/doc/api-reference/widgets/current-refinements/js#param-excluded-attributes).
  In the example below, only the `categories` attribute is included in the widget.

  ```js JavaScript icon=code theme={"system"}
  currentRefinements({
    // ...
    includedAttributes: ["categories"],
  });
  ```
</ParamField>

<ParamField body="excludedAttributes" type="string[]" default="['query']">
  The attributes to exclude from the widget. Cannot be used with [`includedAttributes`](/doc/api-reference/widgets/current-refinements/js#param-included-attributes). In the example below, the `brand` attribute is excluded from the widget.

  ```js JavaScript icon=code theme={"system"}
  currentRefinements({
    // ...
    excludedAttributes: ["brand"],
  });
  ```
</ParamField>

<ParamField body="cssClasses" type="object" default="{}">
  The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js#style-your-widgets):

  * `root`. The root element of the widget.
  * `noRefinementRoot`. The root element if there are no refinements.
  * `list`. The list element.
  * `item`. The list items.
  * `label`. The label element of each item.
  * `category`. The container of each item value.
  * `categoryLabel`. The text element of each item value.
  * `delete`. The button element of eatch item value.

  ```js JavaScript icon=code theme={"system"}
  currentRefinements({
    // ...
    cssClasses: {
      root: "MyCustomCurrentRefinements",
      list: [
        "MyCustomCurrentRefinementsList",
        "MyCustomCurrentRefinementsList--subclass",
      ],
    },
  });
  ```
</ParamField>

<ParamField body="transformItems" type="function" default="items => items">
  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](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/)
  and [parameters from the helper](https://community.algolia.com/algoliasearch-helper-js/reference.html#query-parameters),
  such as `disjunctiveFacetsRefinements`.

  ```js JavaScript icon=code theme={"system"}
  currentRefinements({
    // ...
    transformItems(items) {
      return items.filter((item) => item.attribute !== "brand");
    },
  });

  // or, combined with results
  currentRefinements({
    // ...
    transformItems(items, { results }) {
      return results.nbHits === 0
        ? items
        : items.filter((item) => item.attribute !== "brand");
    },
  });
  ```
</ParamField>

## HTML output

```html HTML icon=code-xml theme={"system"}
<div class="ais-CurrentRefinements">
  <ul class="ais-CurrentRefinements-list">
    <li class="ais-CurrentRefinements-item">
      <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>
```

## Customize the UI with `connectCurrentRefinements`

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

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

<CodeGroup>
  ```js Package manager theme={"system"}
  import { connectCurrentRefinements } from "instantsearch.js/es/connectors";
  ```

  ```js CDN theme={"system"}
  const { connectCurrentRefinements } = instantsearch.connectors;
  // or directly use instantsearch.connectors.connectCurrentRefinements()
  ```
</CodeGroup>

Then it's a 3-step process:

```js JavaScript icon=code theme={"system"}
// 1. Create a render function
const renderCurrentRefinements = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customCurrentRefinements = connectCurrentRefinements(
  renderCurrentRefinements,
);

// 3. Instantiate
search.addWidgets([
  customCurrentRefinements({
    // instance params
  }),
]);
```

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

```js JavaScript icon=code theme={"system"}
const renderCurrentRefinements = (renderOptions, isFirstRender) => {
  const { items, canRefine, refine, createURL, widgetParams } = renderOptions;

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

  // Render the widget
};
```

#### Rendering options

<ParamField body="items" type="object[]">
  All the currently refined items, grouped by attribute.

  With each item:

  * `indexName: string`. The index name on which the refinement is applied.
  * `indexId: string`. The index id on which the refinement is applied.
  * `attribute: string`. The attribute on which the refinement is applied.
  * `label: string`. The textual representation of this attribute.
  * `refine: function`. Removes the refinement.
  * `refinements: object[]`. Currently applied refinements.

  With each [refinement](/doc/api-reference/widgets/refinement-list/js):

  * `type: 'facet' | 'exclude' | 'disjunctive' | 'hierarchical' | 'numeric' | 'query'`. The type of the refinement.
  * `attribute: string`. The attribute on which the refinement is applied.
  * `label: string`. The label of the refinement to display.
  * `value: string`. The raw value of the refinement.
  * `operator?: string`. The value of the operator (only if applicable).
  * `exhaustive?: boolean`. Whether the count is exhaustive (only if applicable).
  * `count?: number`. The number of found items (only if applicable).

  ```js JavaScript icon=code theme={"system"}
  const renderListItem = (item) => `
    <li>
      ${item.attribute}
      <ul>
        ${item.refinements
          .map(
            (refinement) => `<li>${refinement.value} (${refinement.count})</li>`,
          )
          .join("")}
      </ul>
    </li>
  `;

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

    document.querySelector("#current-refinements").innerHTML = `
      <ul>
        ${items.map(renderListItem).join("")}
      </ul>
    `;
  };
  ```
</ParamField>

<ParamField body="canRefine" type="boolean" required>
  Indicates if search state can be refined.

  ```js JavaScript icon=code theme={"system"}
  const renderCurrentRefinements = (renderOptions, isFirstRender) => {
    const { canRefine } = renderOptions;

    if (!canRefine) {
      document.querySelector("#current-refinements").innerHTML = "";
      return;
    }
  };
  ```
</ParamField>

<ParamField body="refine" type="function">
  Clears a single [refinement](/doc/api-reference/widgets/refinement-list/js) and triggers a new search.

  ```js JavaScript icon=code theme={"system"}
  const createDataAttribtues = (refinement) =>
    Object.keys(refinement)
      .map((key) => `data-${key}="${refinement[key]}"`)
      .join(" ");

  const renderListItem = (item) => `
    <li>
      ${item.label}
      <ul>
        ${item.refinements
          .map(
            (refinement) =>
              `<li>
                ${refinement.label} (${refinement.count})
                <button ${createDataAttribtues(refinement)}>X</button>
              </li>`,
          )
          .join("")}
      </ul>
    </li>
  `;

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

    const container = document.querySelector("#current-refinements");

    container.innerHTML = `
      <ul>
        ${items.map(renderListItem).join("")}
      </ul>
    `;

    [...container.querySelectorAll("button")].forEach((element) => {
      element.addEventListener("click", (event) => {
        const item = Object.keys(event.currentTarget.dataset).reduce(
          (acc, key) => ({
            ...acc,
            [key]: event.currentTarget.dataset[key],
          }),
          {},
        );

        refine(item);
      });
    });
  };
  ```
</ParamField>

<ParamField body="createURL" type="function">
  Generates a URL for the next state.

  ```js JavaScript icon=code theme={"system"}
  const renderListItem = ({ item, createURL }) => `
    <li>
      ${item.label}
      <ul>
        ${item.refinements
          .map(
            (refinement) =>
              `<li>
                <a href="${createURL(refinement)}">
                  ${refinement.label} (${refinement.count})
                </a>
              </li>`,
          )
          .join("")}
      </ul>
    </li>
  `;

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

    document.querySelector("#current-refinements").innerHTML = `
      <ul>
        ${items.map((item) => renderListItem({ item, createURL })).join("")}
      </ul>
    `;
  };
  ```
</ParamField>

<ParamField body="widgetParams" type="object">
  All original widget options forwarded to the render function.

  ```js JavaScript icon=code theme={"system"}
  const renderCurrentRefinements = (renderOptions, isFirstRender) => {
    const { widgetParams } = renderOptions;

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

  // ...

  search.addWidgets([
    customCurrentRefinements({
      container: document.querySelector("#current-refinements"),
    }),
  ]);
  ```
</ParamField>

### 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`.

```js JavaScript icon=code theme={"system"}
const customCurrentRefinements = connectCurrentRefinements(
  renderCurrentRefinements
);

search.addWidgets([
  customCurrentRefinements({
    // Optional parameters
    includedAttributes: string[],
    excludedAttributes: string[],
    transformItems: function,
  })
]);
```

#### Instance options

<ParamField body="includedAttributes" type="string[]" default="[]">
  The attributes to include in the widget (all by default).
  Cannot be used with [`excludedAttributes`](/doc/api-reference/widgets/current-refinements/js#param-excluded-attributes).
  In the example below, only the `categories` attribute is included in the widget.

  ```js JavaScript icon=code theme={"system"}
  customCurrentRefinements({
    includedAttributes: ["categories"],
  });
  ```
</ParamField>

<ParamField body="excludedAttributes" type="string[]" default="['query']">
  The attributes to exclude from the widget.
  Cannot be used with [`includedAttributes`](/doc/api-reference/widgets/current-refinements/js#param-included-attributes).
  In the example below, the `brand` attribute is excluded from the widget.

  ```js JavaScript icon=code theme={"system"}
  customCurrentRefinements({
    excludedAttributes: ["brand"],
  });
  ```
</ParamField>

<ParamField body="transformItems" type="function" default="items => items">
  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](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/)
  and [parameters from the helper](https://community.algolia.com/algoliasearch-helper-js/reference.html#query-parameters),
  such as `disjunctiveFacetsRefinements`.

  ```js JavaScript icon=code theme={"system"}
  customCurrentRefinements({
    transformItems(items) {
      return items.filter((item) => item.attribute !== "brand");
    },
  });

  /* or, combined with results */
  customCurrentRefinements({
    transformItems(items, { results }) {
      return results.nbHits === 0
        ? items
        : items.filter((item) => item.attribute !== "brand");
    },
  });
  ```
</ParamField>

### Full example

<CodeGroup>
  ```html HTML theme={"system"}
  <div id="current-refinements"></div>
  ```

  ```js JavaScript theme={"system"}
  // Create the render function
  const createDataAttribtues = (refinement) =>
    Object.keys(refinement)
      .map((key) => `data-${key}="${refinement[key]}"`)
      .join(" ");

  const renderListItem = (item) => `
    <li>
      ${item.label}
      <ul>
        ${item.refinements
          .map(
            (refinement) =>
              `<li>
                ${refinement.label} (${refinement.count})
                <button ${createDataAttribtues(refinement)}>X</button>
              </li>`,
          )
          .join("")}
      </ul>
    </li>
  `;

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

    widgetParams.container.innerHTML = `
      <ul>
        ${items.map(renderListItem).join("")}
      </ul>
    `;

    [...widgetParams.container.querySelectorAll("button")].forEach((element) => {
      element.addEventListener("click", (event) => {
        const item = Object.keys(event.currentTarget.dataset).reduce(
          (acc, key) => ({
            ...acc,
            [key]: event.currentTarget.dataset[key],
          }),
          {},
        );

        refine(item);
      });
    });
  };

  // Create the custom widget
  const customCurrentRefinements = connectCurrentRefinements(
    renderCurrentRefinements,
  );

  // Instantiate the custom widget
  search.addWidgets([
    customCurrentRefinements({
      container: document.querySelector("#current-refinements"),
    }),
  ]);
  ```
</CodeGroup>