Skip to main content
The ToggleRefinement connector provides the logic to build a custom widget that provides an on/off filtering feature based on an attribute value or values. Two modes are implemented:
  • With or without the value filtered
  • Switch between two values

​
Usage

import { connectToggleRefinement } from 'instantsearch.js/es/connectors';

const customToggleRefinement = connectToggleRefinement(
  (renderOptions, isFirstRender) => {
    const { value, refine, widgetParams } = renderOptions;
    const { container } = widgetParams;
    
    container.innerHTML = `
      <label>
        <input 
          type="checkbox" 
          ${value.isRefined ? 'checked' : ''}
        />
        ${value.name} (${value.count})
      </label>
    `;
    
    container.querySelector('input').addEventListener('change', () => {
      refine({ isRefined: !value.isRefined });
    });
  }
);

search.addWidgets([
  customToggleRefinement({
    container: document.querySelector('#toggle'),
    attribute: 'free_shipping',
  }),
]);

​
Connector Options

​
attribute
string
required
Name of the attribute for faceting (e.g., “free_shipping”).
​
on
string | number | boolean | Array
default:"true"
Value to filter on when toggled on.
​
off
string | number | boolean | Array
Value to filter on when toggled off.

​
Render Options

​
value
object
The current toggle value with the following properties:
  • name: The attribute name of this toggle
  • isRefined: Whether the current option is “on” (true) or “off” (false)
  • count: Number of results if this option is toggled
  • onFacetValue: Information about the “on” toggle
  • offFacetValue: Information about the “off” toggle
​
refine
(value?: { isRefined: boolean }) => void
Updates to the next state by applying the toggle refinement.
​
createURL
() => string
Creates a URL for the next state.
​
canRefine
boolean
Indicates if search state can be refined.
​
sendEvent
function
Sends a “Facet Clicked” Insights event.
​
widgetParams
object
The options passed to the connector.

Build docs developers (and LLMs) love

Get started for freeTalk to us