> ## 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 FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
```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
```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()
```
Preview this widget and its behavior.
## 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
The CSS Selector or `HTMLElement` to insert the widget into.
```js string theme={"system"}
toggleRefinement({
// ...
container: "#toggle-refinement",
});
```
```js HTMLElement theme={"system"}
toggleRefinement({
// ...
container: document.querySelector("#toggle-refinement"),
});
```
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",
});
```
The value of the refinement to apply on the attribute when checked.
```js boolean theme={"system"}
toggleRefinement({
// ...
on: false,
});
```
```js number theme={"system"}
toggleRefinement({
// ...
on: 10,
});
```
```js string theme={"system"}
toggleRefinement({
// ...
on: "apple",
});
```
The value of the refinement to apply on the attribute when unchecked.
```js boolean theme={"system"}
toggleRefinement({
// ...
off: false,
});
```
```js number theme={"system"}
toggleRefinement({
// ...
off: 10,
});
```
```js string theme={"system"}
toggleRefinement({
// ...
off: "apple",
});
```
The [templates](#templates) to use for the widget.
```js JavaScript icon=code theme={"system"}
toggleRefinement({
// ...
templates: {
// ...
},
});
```
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",
],
},
});
```
## 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).
The `html` function is available in InstantSearch.js version 4.46.0 or later.
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).
```js function theme={"system"}
toggleRefinement({
// ...
templates: {
labelText({ count }, { html }) {
return html`Free shipping (${count.toLocaleString()})`;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
toggleRefinement({
// ...
templates: {
labelText: "Free shipping ({{ count }})",
},
});
```
## HTML output
```html HTML icon=code-xml theme={"system"}
```
## 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.
```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()
```
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
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 = `
`;
};
```
Indicates if search state can be refined.
```js JavaScript icon=code theme={"system"}
const { canRefine } = renderOptions;
if (!canRefine) {
document.querySelector("#toggle-refinement").innerHTML = "";
return;
}
```
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;
};
```
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',
}
*/
```
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 = `
Link to the next state
`;
};
```
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"),
}),
]);
```
### 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
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",
});
```
The value of the refinement to apply on the attribute when checked.
```js boolean theme={"system"}
customToggleRefinement({
// ...
on: false,
});
```
```js number theme={"system"}
customToggleRefinement({
// ...
on: 10,
});
```
```js string theme={"system"}
customToggleRefinement({
// ...
on: "apple",
});
```
The value of the refinement to apply on the attribute when unchecked.
```js boolean theme={"system"}
customToggleRefinement({
// ...
off: false,
});
```
```js number theme={"system"}
customToggleRefinement({
// ...
off: 10,
});
```
```js string theme={"system"}
customToggleRefinement({
// ...
off: "apple",
});
```
### Full example
```html HTML theme={"system"}
```
```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",
}),
]);
```