Skip to main content
The toggleRefinement widget creates a checkbox that toggles a facet filter on or off. It’s ideal for boolean filters like “Free shipping”, “In stock”, or “On sale”.

​
Usage

const toggleRefinement = instantsearch.widgets.toggleRefinement({
  container: '#free-shipping',
  attribute: 'free_shipping',
  on: true,
});

search.addWidget(toggleRefinement);

​
Examples

​
Basic Toggle

instantsearch.widgets.toggleRefinement({
  container: '#free-shipping',
  attribute: 'free_shipping',
  templates: {
    labelText: 'Free shipping',
  },
});

​
Toggle with Custom Values

instantsearch.widgets.toggleRefinement({
  container: '#availability',
  attribute: 'available',
  on: 'yes',
  off: 'no',
  templates: {
    labelText: 'In stock only',
  },
});

​
Toggle with Dynamic Label

instantsearch.widgets.toggleRefinement({
  container: '#on-sale',
  attribute: 'on_sale',
  templates: {
    labelText({ isRefined }) {
      return isRefined ? 'Showing sale items' : 'Show sale items only';
    },
  },
});

​
Options

​
container
string | HTMLElement
required
CSS Selector or HTMLElement to insert the widget.
​
attribute
string
required
The name of the attribute to filter on. Must be declared as an attribute for faceting.
​
on
any
default:"true"
The value to filter on when the toggle is checked.
​
off
any
The value to filter on when the toggle is unchecked. When not provided, the filter is simply removed when unchecked.
​
templates
object
Templates to customize the widget rendering.
​
cssClasses
object
CSS classes to add to the widget elements.

​
HTML Output

<div class="ais-ToggleRefinement">
  <label class="ais-ToggleRefinement-label">
    <input
      class="ais-ToggleRefinement-checkbox"
      type="checkbox"
      checked
    />
    <span class="ais-ToggleRefinement-labelText">Free shipping</span>
  </label>
</div>

​
Use Cases

​
Boolean Filters

instantsearch.widgets.toggleRefinement({
  container: '#free-shipping',
  attribute: 'free_shipping',
  templates: {
    labelText: 'Free shipping',
  },
});

​
String Value Filters

instantsearch.widgets.toggleRefinement({
  container: '#brand-filter',
  attribute: 'brand',
  on: 'Apple',
  templates: {
    labelText: 'Apple products only',
  },
});

​
Toggle Between Two Values

instantsearch.widgets.toggleRefinement({
  container: '#condition',
  attribute: 'condition',
  on: 'new',
  off: 'used',
  templates: {
    labelText: 'New items only',
  },
});

​
Requirements

The attribute must be declared as an attribute for faceting in your Algolia index settings.

Build docs developers (and LLMs) love

Get started for freeTalk to us