> ## 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 = () =>
records
;
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
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/).
```tsx Signature theme={"system"}
}
/>
```
## Import
```jsx JavaScript icon=code theme={"system"}
import { ToggleRefinement } from "react-instantsearch";
```
Preview this widget and its behavior.
## About this widget
`` 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`](#hook).
### 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 (
);
}
```
## Props
The name of the attribute in the .
To avoid unexpected behavior, you can't use the same `attribute` prop in a different type of widget.
```jsx JavaScript icon=code theme={"system"}
;
```
The label to display for the checkbox.
```jsx JavaScript icon=code theme={"system"}
;
```
The value of the refinement to apply on the attribute when checked.
```jsx boolean theme={"system"}
;
```
```jsx number theme={"system"}
;
```
```jsx String theme={"system"}
;
```
The value of the refinement to apply on the attribute when unchecked.
```jsx boolean theme={"system"}
;
```
```jsx number theme={"system"}
;
```
```jsx String theme={"system"}
;
```
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"}
;
```
Any `
` prop to forward to the root element of the widget.
```jsx JavaScript icon=code theme={"system"}
;
```
## Hook
React InstantSearch let you create your own UI for the `` 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 [``](/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"}
```
### 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()`](https://reactjs.org/docs/hooks-reference.html#usecallback) for memoization.
Arrays and objects are automatically memoized.
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",
});
```
The value of the refinement to apply on the attribute when checked.
```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",
});
```
The value of the refinement to apply on the attribute when unchecked.
```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",
});
```
### APIs
Hooks return APIs, such as state and functions.
You can use them to build your UI and interact with React InstantSearch.
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;
};
```
Whether the search state can be refined.
```jsx JavaScript icon=code theme={"system"}
const { canRefine } = useToggleRefinement({ attribute: "free_shipping" });
return ;
```
Updates to the next state by applying the toggle refinement.
```jsx JavaScript icon=code theme={"system"}
const { refine } = useToggleRefinement({ attribute: "free_shipping" });
return (
refine({ isRefined: !event.target.checked })}
type="checkbox"
/>
);
```
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',
// }
```
Generates a URL for the next state.
```jsx JavaScript icon=code theme={"system"}
const { createURL, value, refine } = useToggleRefinement({
attribute: "free_shipping",
});
return (
refine({ isRefined: !value.isRefined })}
>
Link to the next state
);
```
### Example
```jsx JavaScript theme={"system"}
import React from "react";
import { useToggleRefinement } from "react-instantsearch";
function CustomToggleRefinement(props) {
const { value, refine } = useToggleRefinement(props);
return (
);
}
```
```tsx TypeScript theme={"system"}
import React from "react";
import {
useToggleRefinement,
UseToggleRefinementProps,
} from "react-instantsearch";
function CustomToggleRefinement(props: UseToggleRefinementProps) {
const { value, refine } = useToggleRefinement(props);
return (
);
}
```