widgets toggle

Edit this page

Description

The toggle widget lets the user either:

  • switch between two values for a single facetted attribute (free_shipping / not_free_shipping)
  • toggle 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 attributeName 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

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

const widget = instantsearch.widgets.toggle({ container: string|HTMLElement, attributeName: string, label: string, values: [ToggleWidgetValues], templates: [ToggleWidgetTemplates], transformData: [ToggleWidgetTransforms], autoHideContainer: [boolean], cssClasses: [ToggleWidgetCSSClasses], collapsible: boolean|ToggleWidgetCollapsibleOption, }: ToggleWidgetOptions);
search.addWidget(widget);

Options

ToggleWidgetOptions

  • containerstring|HTMLElement

    Place where to insert the widget in your webpage.

  • attributeNamestring

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

  • labelstring

    Human-readable name of the filter (eg. “Free Shipping”).

  • values[ToggleWidgetValues]
    Default value: {on:true,off:undefined}

    Values that the widget can set.

  • templates[ToggleWidgetTemplates]

    Templates to use for the widget.

  • transformData[ToggleWidgetTransforms]

    Object that contains the functions to be applied on the data * before being used for templating. Valid keys are body for the body template.

  • autoHideContainer[boolean]
    Default value: true

    Make the widget hides itself when there is no results matching.

  • cssClasses[ToggleWidgetCSSClasses]

    CSS classes to add.

  • collapsibleboolean|ToggleWidgetCollapsibleOption

    If set to true, the widget can be collapsed. This parameter can also be an object, with the property collapsed, if you want the toggle to be collapsed initially.

ToggleWidgetValues

  • 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.

ToggleWidgetTemplates

  • headerstring|function

    Header template.

  • itemstring|function

    Item template, provided with name, count, isRefined, url data properties. count is always the number of hits that would be shown if you toggle the widget. We also provide onFacetValue and offFacetValue objects with according counts.

ToggleWidgetTransforms

  • item(Object) => Object

    Function to change the object passed to the item. template

ToggleWidgetCSSClasses

  • root[string|Array<string>]

    CSS class to add to the root element.

  • header[string|Array<string>]

    CSS class to add to the header element.

  • body[string|Array<string>]

    CSS class to add to the body element.

  • list[string|Array<string>]

    CSS class to add to the list element.

  • item[string|Array<string>]

    CSS class to add to each item element.

  • active[string|Array<string>]

    CSS class to add to each active element.

  • label[string|Array<string>]

    CSS class to add to each label element (when using the default template).

  • checkbox[string|Array<string>]

    CSS class to add to each checkbox element (when using the default template).

  • count[string|Array<string>]

    CSS class to add to each count.

ToggleWidgetCollapsibleOption

  • collapsedboolean

    If set to true, the widget will be collapsed at first rendering.

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.toggle({
    container: '#free-shipping',
    attributeName: 'free_shipping',
    label: 'Free Shipping',
    values: {
      on: true,
    },
    templates: {
      header: 'Shipping'
    }
  })
);

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