ToggleRefinement

Lets users toggle a specific filter.

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

<ToggleRefinement
  attribute={string}
  // Optional parameters
  label={string}
  on={boolean | number | string}
  off={boolean | number | string}
  classNames={object}
  ...props={ComponentProps<'div'>}
/>

Import

JavaScript

import { ToggleRefinement } from "react-instantsearch";

View demo

About this widget

<ToggleRefinement> is a widget that provides an on/off filter based on an attribute value.

For example, you can use this widget to only display products that apply for free shipping, or recipes that are gluten-free.

You can also create your own UI with useToggleRefinement.

Requirements

Make sure to declare the provided attribute as an attribute for faceting.

Examples

JavaScript

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

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

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

Props

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

<ToggleRefinement attribute="free_shipping" />;

label · string

The label to display for the checkbox.

JavaScript

<ToggleRefinement
  // ...
  label="Free shipping"
/>;

on · boolean | string | number

The value of the refinement to apply on the attribute when checked.

boolean

<ToggleRefinement
  // ...
  on={true}
/>;

off · boolean | string | number

The value of the refinement to apply on the attribute when unchecked.

boolean

<ToggleRefinement
  // ...
  off={false}
/>;

classNames · Partial<ToggleRefinementClassNames>

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.
• label. The label element.
• checkbox. The checkbox element.
• labelText. The text element of the label.

JavaScript

<ToggleRefinement
  // ...
  classNames={{
    root: "MyCustomToggleRefinement",
    checkbox:
      "MyCustomToggleRefinementCheckbox MyCustomToggleRefinementCheckbox--subclass",
  }}
/>;

...props · React.ComponentProps<'div'>

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

JavaScript

<ToggleRefinement
  // ...
  className="MyCustomToggleRefinement"
  title="My custom title"
/>;

Hook

React InstantSearch let you create your own UI for the <ToggleRefinement> widget with useToggleRefinement. Hooks provide APIs to access the widget state and interact with InstantSearch.

The useToggleRefinement Hook accepts parameters and returns APIs. It must be used inside the <InstantSearch> component.

Usage

First, create your React component:

JavaScript

import { useToggleRefinement } from "react-instantsearch";

function CustomToggleRefinement(props) {
  const { value, canRefine, refine, sendEvent, createURL } =
    useToggleRefinement(props);

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

Then, render the widget:

JavaScript

<CustomToggleRefinement {...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.

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

const toggleRefinementApi = useToggleRefinement({
  attribute: "free_shipping",
});

on · boolean | string | number

The value of the refinement to apply on the attribute when checked.

boolean

const toggleRefinementApi = useToggleRefinement({
  // ...
  on: true,
});

off · boolean | string | number

The value of the refinement to apply on the attribute when unchecked.

boolean

const toggleRefinementApi = useToggleRefinement({
  // ...
  off: false,
});

APIs

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

value · ToggleRefinementValue

The current refinement.

TypeScript

type ToggleRefinementValue = {
  /**
   * The attribute name of this toggle.
   */
  name: string;
  /**
   * Whether the current option is "on" (true) or "off" (false)
   */
  isRefined: boolean;
  /**
   * Number of results if this option is toggled.
   */
  count: number | null;
  /**
   * Information about the "on" toggle.
   */
  onFacetValue: ToggleRefinementDetails;
  /**
   * Information about the "off" toggle.
   */
  offFacetValue: ToggleRefinementDetails;
};

type ToggleRefinementDetails = {
  /**
   * whether this option is enabled.
   */
  isRefined: boolean;
  /**
   * Number of result if this option is toggled.
   */
  count: number | null;
};

canRefine · boolean

Whether the search state can be refined.

JavaScript

const { canRefine } = useToggleRefinement({ attribute: "free_shipping" });

return <input disabled={!canRefine} type="checkbox" />;

refine · ({ isRefined: boolean }) => void

Updates to the next state by applying the toggle refinement.

JavaScript

const { refine } = useToggleRefinement({ attribute: "free_shipping" });

return (
  <input
    onChange={(event) => refine({ isRefined: !event.target.checked })}
    type="checkbox"
  />
);

sendEvent · (eventType: string, facetValue: string, eventName?: string) => void

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

JavaScript

sendEvent("click", true);

// This sends a similar payload to the `insights` middleware.
// {
// eventType: 'click',
// insightsMethod: 'clickedFilters',
// payload: {
// eventName: 'Filter Applied',
// filters: ['free_shipping:true'],
// index: '',
// },
// widgetType: 'ais.toggleRefinement',
// }

createURL · () => string

Generates a URL for the next state.

JavaScript

const { createURL, value, refine } = useToggleRefinement({
  attribute: "free_shipping",
});

return (
  <a
    href={createURL()}
    onClick={(event) => refine({ isRefined: !value.isRefined })}
  >
    Link to the next state
  </a>
);

Example

JavaScript

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

function CustomToggleRefinement(props) {
  const { value, refine } = useToggleRefinement(props);

  return (
    <label>
      <input
        type="checkbox"
        checked={value.isRefined}
        onChange={(event) => {
          refine({ isRefined: !event.target.checked });
        }}
      />

      <span>{props.attribute}</span>
    </label>
  );
}