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

```ts Signature theme={"system"}
toggleRefinement({
  container: string | HTMLElement,
  attribute: string,
  // Optional parameters
  on?: boolean | number | string,
  off?: boolean | number | string,
  templates?: object,
  cssClasses?: object,
});
```

## Import

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

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

<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

The `toggleRefinement` widget provides an on/off filtering feature based on an attribute value.

### Requirements

Ensure that the attribute provided is already declared as an [attribute for faceting](/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting).

## Examples

```js JavaScript icon=code theme={"system"}
toggleRefinement({
  container: "#toggle-refinement",
  attribute: "free_shipping",
  templates: {
    labelText({ count }, { html }) {
      return html`Free shipping (${count.toLocaleString()})`;
    },
  },
});
```

## Options

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

  <CodeGroup>
    ```js string theme={"system"}
    toggleRefinement({
      // ...
      container: "#toggle-refinement",
    });
    ```

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

<ParamField body="attribute" type="string" required>
  The name of the attribute on which apply the refinement.

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

  ```js JavaScript icon=code theme={"system"}
  toggleRefinement({
    // ...
    attribute: "free_shipping",
  });
  ```
</ParamField>

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

  <CodeGroup>
    ```js boolean theme={"system"}
    toggleRefinement({
      // ...
      on: false,
    });
    ```

    ```js number theme={"system"}
    toggleRefinement({
      // ...
      on: 10,
    });
    ```

    ```js string theme={"system"}
    toggleRefinement({
      // ...
      on: "apple",
    });
    ```
  </CodeGroup>
</ParamField>

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

  <CodeGroup>
    ```js boolean theme={"system"}
    toggleRefinement({
      // ...
      off: false,
    });
    ```

    ```js number theme={"system"}
    toggleRefinement({
      // ...
      off: 10,
    });
    ```

    ```js string theme={"system"}
    toggleRefinement({
      // ...
      off: "apple",
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="templates" type="object">
  The [templates](#templates) to use for the widget.

  ```js JavaScript icon=code theme={"system"}
  toggleRefinement({
    // ...
    templates: {
      // ...
    },
  });
  ```
</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.
  * `label`. The label of the toggle.
  * `checkbox`. The checkbox element of the toggle.
  * `labelText`. The label text of the toggle.

  ```js JavaScript icon=code theme={"system"}
  toggleRefinement({
    // ...
    cssClasses: {
      root: "MyCustomToggleRefinement",
      label: [
        "MyCustomToggleRefinementLabel",
        "MyCustomToggleRefinementLabel--subclass",
      ],
    },
  });
  ```
</ParamField>

## 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates).
This function safely renders templates as HTML strings and works directly in the browser—no build step required.
For details, see [Templating your UI](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js/#templating-your-ui).

<Note>
  The `html` function is available in InstantSearch.js version 4.46.0 or later.
</Note>

<ParamField body="labelText" type="string | function">
  The template to use to customize the label. It exposes:

  * `isRefined: boolean`. Indicates whether the checkbox is checked.
  * `count: number`. Shows the number of results after the refinement was applied.
  * `onFacetValue: object`. Describes the value for the attribute. It contains `count` (useful to get the raw value of the count).
  * `offFacetValue: object`. Describes the value for the attribute. It contains `count` (useful to get the raw value of the count).

  <CodeGroup>
    ```js function theme={"system"}
    toggleRefinement({
      // ...
      templates: {
        labelText({ count }, { html }) {
          return html`<span>Free shipping (${count.toLocaleString()})</span>`;
        },
      },
    });
    ```

    ```js string theme={"system"}
    // String-based templates are deprecated, use functions instead.
    toggleRefinement({
      // ...
      templates: {
        labelText: "Free shipping ({{ count }})",
      },
    });
    ```
  </CodeGroup>
</ParamField>

## HTML output

```html HTML icon=code-xml theme={"system"}
<div class="ais-ToggleRefinement">
  <label class="ais-ToggleRefinement-label">
    <input class="ais-ToggleRefinement-checkbox" type="checkbox" />
    <span class="ais-ToggleRefinement-labelText">Free Shipping</span>
    <span class="ais-ToggleRefinement-count">18,013</span>
  </label>
</div>
```

## Customize the UI with `connectToggleRefinement`

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

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

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

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

Then it's a 3-step process:

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

// 2. Create the custom widget
const customToggleRefinement = connectToggleRefinement(renderToggleRefinement);

// 3. Instantiate
search.addWidgets([
  customToggleRefinement({
    // 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 renderToggleRefinement = (renderOptions, isFirstRender) => {
  const { value, canRefine, refine, sendEvent, createURL, widgetParams } =
    renderOptions;

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

  // Render the widget
};
```

#### Rendering options

<ParamField body="value" type="object">
  The current refinement, with:

  * `isRefined: boolean`. Indicates whether the checkbox is checked.
  * `count: number`. Shows the number of results after the refinement was applied.
  * `onFacetValue: object`. Describes the value for the attribute. It contains `count` (useful to get the raw value of the count).
  * `offFacetValue: object`. Describes the value for the attribute. It contains `count` (useful to get the raw value of the count).

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

    document.querySelector("#toggle-refinement").innerHTML = `
      <label>
        <input type="checkbox" ${value.isRefined ? "checked" : ""} />
        Free shipping (${value.count})
      </label>
    `;
  };
  ```
</ParamField>

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

  ```js JavaScript icon=code theme={"system"}
  const { canRefine } = renderOptions;

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

<ParamField body="refine" type="function">
  Updates to the next state by applying the toggle refinement.

  ```js JavaScript icon=code theme={"system"}
  const renderToggleRefinement = (renderOptions, isFirstRender) => {
    const { value, refine } = renderOptions;
    const container = document.querySelector("#toggle-refinement");

    if (isFirstRender) {
      const label = document.createElement("label");
      const input = document.createElement("input");
      input.type = "checkbox";

      input.addEventListener("change", (event) => {
        refine({ isRefined: !event.target.checked });
      });

      label.appendChild(input);
      label.appendChild(document.createTextNode("Free shipping"));
      container.appendChild(label);
    }

    container.querySelector("input").checked = value.isRefined;
  };
  ```
</ParamField>

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

  * `eventType: 'click'`
  * `facetValue: string`

  ```js JavaScript icon=code theme={"system"}
  // For example,
  sendEvent("click", true);

  /*
    A payload like the following will be sent to the `insights` middleware.
    {
      eventType: 'click',
      insightsMethod: 'clickedFilters',
      payload: {
        eventName: 'Filter Applied',
        filters: ['isShippingFree:true'],
        index: '',
      },
      widgetType: 'ais.toggleRefinement',
    }
  */
  ```
</ParamField>

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

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

    document.querySelector("#toggle-refinement").innerHTML = `
      <a href="${createURL()}">Link to the next state</a>
    `;
  };
  ```
</ParamField>

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

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

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

  // ...

  search.addWidgets([
    customToggleRefinement({
      container: document.querySelector("#toggle-refinement"),
    }),
  ]);
  ```
</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`.

```tsx TSX theme={"system"}
const customToggleRefinement = connectToggleRefinement(renderToggleRefinement);

search.addWidgets([
  customToggleRefinement({
    attribute: string,
    // Optional parameters
    on: boolean | number | string,
    off: boolean | number | string,
  }),
]);
```

#### Instance options

<ParamField body="attribute" type="string" required>
  The name of the attribute on which to apply the refinement.

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

  ```js JavaScript icon=code theme={"system"}
  customToggleRefinement({
    attribute: "free_shipping",
  });
  ```
</ParamField>

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

  <CodeGroup>
    ```js boolean theme={"system"}
    customToggleRefinement({
      // ...
      on: false,
    });
    ```

    ```js number theme={"system"}
    customToggleRefinement({
      // ...
      on: 10,
    });
    ```

    ```js string theme={"system"}
    customToggleRefinement({
      // ...
      on: "apple",
    });
    ```
  </CodeGroup>
</ParamField>

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

  <CodeGroup>
    ```js boolean theme={"system"}
    customToggleRefinement({
      // ...
      off: false,
    });
    ```

    ```js number theme={"system"}
    customToggleRefinement({
      // ...
      off: 10,
    });
    ```

    ```js string theme={"system"}
    customToggleRefinement({
      // ...
      off: "apple",
    });
    ```
  </CodeGroup>
</ParamField>

### Full example

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

  ```js JavaScript theme={"system"}
  // Create the render function
  const renderToggleRefinement = (renderOptions, isFirstRender) => {
    const { value, refine, widgetParams } = renderOptions;

    if (isFirstRender) {
      const label = document.createElement("label");
      const input = document.createElement("input");
      input.type = "checkbox";

      const span = document.createElement("span");

      input.addEventListener("change", (event) => {
        refine({ isRefined: !event.target.checked });
      });

      label.appendChild(input);
      label.appendChild(document.createTextNode("Free shipping"));
      label.appendChild(span);

      widgetParams.container.appendChild(label);
    }

    widgetParams.container.querySelector("input").checked = value.isRefined;
    widgetParams.container.querySelector("span").innerHTML =
      value.count !== null ? ` (${value.count})` : "";
  };

  // Create the custom widget
  const customToggleRefinement = connectToggleRefinement(renderToggleRefinement);

  // Instantiate the custom widget
  search.addWidgets([
    customToggleRefinement({
      container: document.querySelector("#toggle-refinement"),
      attribute: "free_shipping",
    }),
  ]);
  ```
</CodeGroup>