widgets toggleRefinement

Description

The toggleRefinement widget lets the user either:

• switch between two values for a single facetted attribute (free_shipping / not_free_shipping)
• toggleRefinement a faceted value on and off (only ‘canon’ for brands)

This widget is particularly useful if you have a boolean value in the records.

Requirements

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

Live example

You can find an example at the end of the page or a live example in our widget showcase.

Usage

const search = instantsearch( /* parameters */ );

const widget = instantsearch.widgets.toggleRefinement({ 
  container: string|HTMLElement, 
  attribute: string, 
  on: string|number|boolean, 
  off: string|number|boolean, 
  templates: [ToggleWidgetTemplates], 
  cssClasses: [ToggleWidgetCSSClasses], 
}: ToggleWidgetOptions);

search.addWidget(widget);

Options

ToggleWidgetOptions

• containerstring|HTMLElement

  Place where to insert the widget in your webpage.

• attributestring

  Name of the attribute for faceting (eg. “free_shipping”).

• onstring|number|boolean

  Value to filter on when checked.

• offstring|number|boolean

  Value to filter on when unchecked. element (when using the default template). By default when switching to off, no refinement will be asked. So you will get both true and false results. If you set the off value to false then you will get only objects having false has a value for the selected attribute.

• templates[ToggleWidgetTemplates]

  Templates to use for the widget.

• cssClasses[ToggleWidgetCSSClasses]

  CSS classes to add.

ToggleWidgetTemplates

• labelTextstring|(object) => string

  the text that describes the toggle action. This template receives some contextual information:

  • isRefined which is true if the checkbox is checked
  • count - the count of the values if the toggle in the next refinements
  • onFacetValue, offFacetValue: objects with count (useful to get the other value of count)

ToggleWidgetCSSClasses

• root[string|Array<string>]

  CSS class to add to the root element.

• label[string|Array<string>]

  CSS class to add to the label wrapping element

• checkbox[string|Array<string>]

  CSS class to add to the checkbox

• labelText[string|Array<string>]

  CSS class to add to the label text.

Widget

• render[function]

  Called after each search response has been received

• getConfiguration[function]

  Let the widget update the configuration of the search with new parameters

• init[function]

  Called once before the first search

Example

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

Can't find what you are looking for? Open an issue, we'll get back to you.