CurrentRefinements

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.

Signature

<CurrentRefinements
  // Optional props
  includedAttributes={string[]}
  excludedAttributes={string[]}
  transformItems={function}
  classNames={object}
  ...props={ComponentProps<'div'>}
/>

Import

JavaScript

import { CurrentRefinements } from "react-instantsearch";

See this widget in action

Preview this widget and its behavior.

<CurrentRefinements> is a widget that lets you display the list of active refinements in the search.

You can also create your own UI with useCurrentRefinements.

Examples

JavaScript

import React from "react";
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { InstantSearch, CurrentRefinements } from "react-instantsearch";

const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <CurrentRefinements />
    </InstantSearch>
  );
}

Props

includedAttributes

string[]

default:"[]"

The attributes to include (all by default). This parameter can’t be used with excludedAttributes.In the example below, only the categories attribute is included.

JavaScript

<CurrentRefinements includedAttributes={["categories"]} />;

excludedAttributes

string[]

default:"['query']"

The attributes to exclude from the widget. This parameter can’t be used with includedAttributes.In the example below, the brand attribute is excluded.

JavaScript

<CurrentRefinements excludedAttributes={["brand"]} />;

transformItems

(items: object[], metadata: { results: SearchResults }) => object[]

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 and parameters from the helper, such as disjunctiveFacetsRefinements.

const transformItems = (items) => {
  return items.filter((item) => item.attribute !== "brand");
};

function Search() {
  return (
    <CurrentRefinements
      // ...
      transformItems={transformItems}
    />
  );
}

import type { CurrentRefinementsProps } from "react-instantsearch";

const transformItems: CurrentRefinementsProps["transformItems"] = (items) => {
  return items.filter((item) => item.attribute !== "brand");
};

function Search() {
  return (
    <CurrentRefinements
      // ...
      transformItems={transformItems}
    />
  );
}

classNames

Partial<CurrentRefinementsClassNames>

The CSS classes you can override and pass to the widget’s elements. It’s useful to style widgets with class-based CSS frameworks like Bootstrap or Tailwind CSS.

root. The root element of the widget.
noRefinementRoot. The root element when there are no refinements.
list. The list element.
noRefinementList. The list element when there are no refinements.
item. Each refinement element.
label. The label of each refinement.
category. The container of each refinement’s value.
categoryLabel. The text element of each refinement’s value.
delete. The delete button of each refinement.

JavaScript

<CurrentRefinements
  classNames={{
    root: "MyCustomCurrentRefinements",
    list: "MyCustomCurrentRefinementsList MyCustomCurrentRefinementsList--subclass",
  }}
/>;

...props

React.ComponentProps<'div'>

Any <div> prop to forward to the root element of the widget.

JavaScript

<CurrentRefinements
  className="MyCustomCurrentRefinements"
  title="My custom title"
/>;

Hook

React InstantSearch let you create your own UI for the <CurrentRefinements> widget with useCurrentRefinements. Hooks provide APIs to access the widget state and interact with InstantSearch. The useCurrentRefinements Hook accepts parameters and returns APIs. It must be used inside the <InstantSearch> component.

Usage

First, create your React component:

JavaScript

import { useCurrentRefinements } from "react-instantsearch";

function CustomCurrentRefinements(props) {
  const { items, canRefine, refine } = useCurrentRefinements(props);

  return <>{/*Your JSX*/}</>;
}

Then, render the widget:

JavaScript

<CustomCurrentRefinements {...props} />

Parameters

Hooks accept parameters. You can either pass them manually or forward props from a custom component.

When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders. Use useCallback() for memoization. Arrays and objects are automatically memoized.

includedAttributes

string[]

default:"[]"

The attributes to include (all by default). This parameter can’t be used with excludedAttributes.In the example below, only the categories attribute is included.

JavaScript

const currentRefinementsApi = useCurrentRefinements({
  includedAttributes: ["categories"],
});

excludedAttributes

string[]

default:"['query']"

The attributes to exclude from the widget. This parameter can’t be used with includedAttributes.In the example below, the brand attribute is excluded.

JavaScript

const currentRefinementsApi = useCurrentRefinements({
  excludedAttributes: ["brand"],
});

transformItems

(items: object[], metadata: { results: SearchResults }) => object[]

default:"items => items"

const transformItems = (items) => {
  return items.filter((item) => item.attribute !== "brand");
};

function CurrentRefinements() {
  const currentRefinementsApi = useCurrentRefinements({
    // ...
    transformItems,
  });

  return <>{/* Your JSX */}</>;
}

import type { UseCurrentRefinementsProps } from "react-instantsearch";

const transformItems: UseCurrentRefinementsProps["transformItems"] = (
  items,
) => {
  return items.filter((item) => item.attribute !== "brand");
};

function CurrentRefinements() {
  const currentRefinementsApi = useCurrentRefinements({
    // ...
    transformItems,
  });

  return <>{/* Your JSX */}</>;
}

APIs

Hooks return APIs, such as state and functions. You can use them to build your UI and interact with React InstantSearch.

items

CurrentRefinementsItem[]

All the currently refined items grouped by attribute.

TypeScript

type CurrentRefinementsItem = {
  /**
   * The index name.
   */
  indexName: string;
  /**
   * The index id.
   */
  indexId: string;
  /**
   * The attribute on which the refinement is applied.
   */
  attribute: string;
  /**
   * The textual representation of this attribute.
   */
  label: string;
  /**
   * Currently applied refinements.
   */
  refinements: CurrentRefinementsRefinement[];
  /**
   * Removes the given refinement and triggers a new search.
   */
  refine(refinement: CurrentRefinementsRefinement): void;
};

type CurrentRefinementsRefinement = {
  /**
   * The attribute on which the refinement is applied.
   */
  attribute: string;
  /**
   * The type of the refinement.
   *
   * It can be one of those: 'facet'|'exclude'|'disjunctive'|'hierarchical'|'numeric'|'query'|'tag'.
   */
  type: string;
  /**
   * The raw value of the refinement.
   */
  value: string | number;
  /**
   * The label of the refinement to display.
   */
  label: string;
  /**
   * The value of the operator (only if applicable).
   */
  operator?: string;
  /**
   * The number of found items (only if applicable).
   */
  count?: number;
  /**
   * Whether the count is exhaustive (only if applicable).
   */
  exhaustive?: boolean;
};

canRefine

boolean

Whether the search state can be refined.

refine

(value: CurrentRefinementsItem) => void

Clears a single refinement and triggers a new search.

Example

import React from "react";
import { useCurrentRefinements } from "react-instantsearch";

function CustomCurrentRefinements(props) {
  const { items, refine } = useCurrentRefinements(props);

  return (
    <ul>
      {items.map((item) => (
        <li key={[item.indexName, item.label].join("/")}>
          <span>{item.label}:</span>
          {item.refinements.map((refinement) => (
            <span key={refinement.label}>
              <span>{refinement.label}</span>
              <button
                type="button"
                onClick={(event) => {
                  if (isModifierClick(event)) {
                    return;
                  }

                  refine(refinement);
                }}
              >
                Remove
              </button>
            </span>
          ))}
        </li>
      ))}
    </ul>
  );
}

function isModifierClick(event) {
  const isMiddleClick = event.button === 1;

  return Boolean(
    isMiddleClick ||
      event.altKey ||
      event.ctrlKey ||
      event.metaKey ||
      event.shiftKey,
  );
}

import React from "react";
import {
  useCurrentRefinements,
  UseCurrentRefinementsProps,
} from "react-instantsearch";

function CustomCurrentRefinements(props: UseCurrentRefinementsProps) {
  const { items, refine } = useCurrentRefinements(props);

  return (
    <ul>
      {items.map((item) => (
        <li key={[item.indexName, item.label].join("/")}>
          <span>{item.label}:</span>
          {item.refinements.map((refinement) => (
            <span key={refinement.label}>
              <span>{refinement.label}</span>
              <button
                type="button"
                onClick={(event) => {
                  if (isModifierClick(event)) {
                    return;
                  }

                  refine(refinement);
                }}
              >
                Remove
              </button>
            </span>
          ))}
        </li>
      ))}
    </ul>
  );
}

function isModifierClick(event: React.MouseEvent) {
  const isMiddleClick = event.button === 1;

  return Boolean(
    isMiddleClick ||
      event.altKey ||
      event.ctrlKey ||
      event.metaKey ||
      event.shiftKey,
  );
}

​Import

See this widget in action

​About this widget

​Examples

​Props

​Hook

​Usage

​Parameters

​APIs

​Example

Import

About this widget

Examples

Props

Hook

Usage

Parameters

APIs

Example