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

# ToggleRefinement

> Lets users toggle a specific filter.

export const Records = () => <Tooltip tip="A record is a searchable object in an Algolia index. Each record consists of named attributes." cta="Algolia records" href="/doc/guides/sending-and-managing-data/prepare-your-data#algolia-records">
    records
  </Tooltip>;

<Note>
  This is the **React InstantSearch v7** documentation.
  If you're upgrading from v6, see the [upgrade guide](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-v6-to-react-instantsearch-v7).
  If you were using React InstantSearch Hooks,
  this v7 documentation applies—just check for [necessary changes](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-hooks-to-react-instantsearch-v7).
  To continue using v6, you can find the [archived documentation](https://algolia.com/old-docs/deprecated/instantsearch/react/v6/api-reference/instantsearch/).
</Note>

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

## Import

```jsx JavaScript icon=code theme={"system"}
import { ToggleRefinement } from "react-instantsearch";
```

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

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

<Tip>You can also create your own UI with [`useToggleRefinement`](#hook).</Tip>

### Requirements

Make sure to declare the provided [`attribute`](#param-attribute) as an [attribute for faceting](/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting).

## Examples

```jsx JavaScript icon=code theme={"system"}
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

<ParamField body="attribute" type="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.

  ```jsx JavaScript icon=code theme={"system"}
  <ToggleRefinement attribute="free_shipping" />;
  ```
</ParamField>

<ParamField body="label" type="string">
  The label to display for the checkbox.

  ```jsx JavaScript icon=code theme={"system"}
  <ToggleRefinement
    // ...
    label="Free shipping"
  />;
  ```
</ParamField>

<ParamField body="on" type="boolean | string | number">
  The value of the refinement to apply on the attribute when checked.

  <CodeGroup>
    ```jsx boolean theme={"system"}
    <ToggleRefinement
      // ...
      on={true}
    />;
    ```

    ```jsx number theme={"system"}
    <ToggleRefinement
      // ...
      on={1}
    />;
    ```

    ```jsx String theme={"system"}
    <ToggleRefinement
      // ...
      on="yes"
    />;
    ```
  </CodeGroup>
</ParamField>

<ParamField body="off" type="boolean | string | number">
  The value of the refinement to apply on the attribute when unchecked.

  <CodeGroup>
    ```jsx boolean theme={"system"}
    <ToggleRefinement
      // ...
      off={false}
    />;
    ```

    ```jsx number theme={"system"}
    <ToggleRefinement
      // ...
      off={0}
    />;
    ```

    ```jsx String theme={"system"}
    <ToggleRefinement
      // ...
      off="no"
    />;
    ```
  </CodeGroup>
</ParamField>

<ParamField body="classNames" type="Partial<ToggleRefinementClassNames>">
  The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/react#style-your-widgets) and pass to the widget's elements.
  It's useful to style widgets with class-based CSS frameworks like [Bootstrap](https://getbootstrap.com) or [Tailwind CSS](https://tailwindcss.com).

  * `root`. The root element of the widget.
  * `label`. The label element.
  * `checkbox`. The checkbox element.
  * `labelText`. The text element of the label.

  ```jsx JavaScript icon=code theme={"system"}
  <ToggleRefinement
    // ...
    classNames={{
      root: "MyCustomToggleRefinement",
      checkbox:
        "MyCustomToggleRefinementCheckbox MyCustomToggleRefinementCheckbox--subclass",
    }}
  />;
  ```
</ParamField>

<ParamField body="...props" type="React.ComponentProps<'div'>">
  Any `<div>` prop to forward to the root element of the widget.

  ```jsx JavaScript icon=code theme={"system"}
  <ToggleRefinement
    // ...
    className="MyCustomToggleRefinement"
    title="My custom title"
  />;
  ```
</ParamField>

## 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](#parameters) and returns [APIs](#hook).
It must be used inside the [`<InstantSearch>`](/doc/api-reference/widgets/instantsearch/react) component.

### Usage

First, create your React component:

```jsx JavaScript icon=code theme={"system"}
import { useToggleRefinement } from "react-instantsearch";

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

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

Then, render the widget:

```jsx JavaScript icon=code theme={"system"}
<CustomToggleRefinement {...props} />
```

### Parameters

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

<Note>
  When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders.
  Use [`useCallback()`](https://reactjs.org/docs/hooks-reference.html#usecallback) for memoization.
  Arrays and objects are automatically memoized.
</Note>

<ParamField body="attribute" type="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.

  ```jsx JavaScript icon=code theme={"system"}
  const toggleRefinementApi = useToggleRefinement({
    attribute: "free_shipping",
  });
  ```
</ParamField>

<ParamField body="on" type="boolean | string | number">
  The value of the refinement to apply on the attribute when checked.

  <CodeGroup>
    ```jsx boolean theme={"system"}
    const toggleRefinementApi = useToggleRefinement({
      // ...
      on: true,
    });
    ```

    ```jsx number theme={"system"}
    const toggleRefinementApi = useToggleRefinement({
      // ...
      on: 1,
    });
    ```

    ```jsx String theme={"system"}
    const toggleRefinementApi = useToggleRefinement({
      // ...
      on: "yes",
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="off" type="boolean | string | number">
  The value of the refinement to apply on the attribute when unchecked.

  <CodeGroup>
    ```jsx boolean theme={"system"}
    const toggleRefinementApi = useToggleRefinement({
      // ...
      off: false,
    });
    ```

    ```jsx number theme={"system"}
    const toggleRefinementApi = useToggleRefinement({
      // ...
      off: 0,
    });
    ```

    ```jsx String theme={"system"}
    const toggleRefinementApi = useToggleRefinement({
      // ...
      off: "no",
    });
    ```
  </CodeGroup>
</ParamField>

### APIs

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

<ParamField body="value" type="ToggleRefinementValue">
  The current refinement.

  ```ts TypeScript icon=code theme={"system"}
  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;
  };
  ```
</ParamField>

<ParamField body="canRefine" type="boolean">
  Whether the search state can be refined.

  ```jsx JavaScript icon=code theme={"system"}
  const { canRefine } = useToggleRefinement({ attribute: "free_shipping" });

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

<ParamField body="refine" type="({ isRefined: boolean }) => void">
  Updates to the next state by applying the toggle refinement.

  ```jsx JavaScript icon=code theme={"system"}
  const { refine } = useToggleRefinement({ attribute: "free_shipping" });

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

<ParamField body="sendEvent" type="(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`](/doc/api-reference/widgets/insights/react) middleware.

  ```jsx JavaScript icon=code theme={"system"}
  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',
  // }
  ```
</ParamField>

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

  ```jsx JavaScript icon=code theme={"system"}
  const { createURL, value, refine } = useToggleRefinement({
    attribute: "free_shipping",
  });

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

### Example

<CodeGroup>
  ```jsx JavaScript theme={"system"}
  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>
    );
  }
  ```

  ```tsx TypeScript theme={"system"}
  import React from "react";
  import {
    useToggleRefinement,
    UseToggleRefinementProps,
  } from "react-instantsearch";

  function CustomToggleRefinement(props: UseToggleRefinementProps) {
    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>
    );
  }
  ```
</CodeGroup>