API Reference / Vue InstantSearch Widgets / ais-toggle-refinement

ais-toggle-refinement

Widget signature 
<ais-toggle-refinement
  attribute="string"
  label="string"
  // Optional parameters
  :on="string|number|boolean"
  :off="string|number|boolean"
  :class-names="object"
/>
See code examples
See Live example

About this widget

The ais-toggle-refinement widget provides an on/off filtering feature based on an attribute value.

Examples

Copy 
1
2
3
4

<ais-toggle-refinement
  attribute="free_shipping"
  label="Free Shipping"
/>

Props

attribute
type: string
Required

The name of the attribute on which to apply the refinement.
Copy 
1
2
3
4

<ais-toggle-refinement
  [...]
  attribute="free_shipping"
/>
label
type: string
Required

The label to display for the checkbox.
Copy 
1
2
3
4

<ais-toggle-refinement
  [...]
  label="Free Shipping"
/>
on
type: string|number|boolean
default: true
Optional

The value of the refinement to apply on the attribute when checked.
Copy 
1
2
3
4

<ais-toggle-refinement
  [...]
  :on="true"
/>
off
type: string|number|boolean
Optional

The value of the refinement to apply on the attribute when unchecked.
Copy 
1
2
3
4

<ais-toggle-refinement
  [...]
  :off="false"
/>
class-names
type: object
default: {}
Optional

The CSS classes to override.

  • ais-ToggleRefinement: the root of the widget.
  • ais-ToggleRefinement--noRefinement: the root of the widget without refinement.
  • ais-ToggleRefinement-label: the label of the toggle.
  • ais-ToggleRefinement-checkbox: the checkbox element of the toggle.
  • ais-ToggleRefinement-labelText: the label text of the toggle.
  • ais-ToggleRefinement-count: the count of the toggle.
Copy 
1
2
3
4
5
6
7
8

<ais-toggle-refinement
  [...]
  :class-names="{
    'ais-ToggleRefinement': 'MyCustomToggleRefinement',
    'ais-ToggleRefinement-label': 'MyCustomToggleRefinementLabel',
    // ...
  }"
/>

Customize the UI

default

The slot to override the complete DOM output of the widget.

Scope

  • value: object: the current refinement. It contains name, count and isRefined.
  • canRefine: boolean: whether or not the refinement can be applied.
  • refine: (value: object) => void: the function to call with the provided value to update the refinement.
  • createURL: (value: object) => void: the function to generate an URL from the provided value.
  • sendEvent: (eventType: 'click', facetValue: string) => void: the function to send click events.
    • The view event is automatically sent when the facets are rendered.
    • The click event is automatically sent when refine is called.
    • You can learn more about the insights middleware.
Copy 
1
2
3
4
5
6
7
8
9
10
11

<ais-toggle-refinement attribute="free_shipping" label="Free Shipping">
  <a
    slot-scope="{ value, refine, createURL, sendEvent }"
    :href="createURL(value)"
    :style="{ fontWeight: value.isRefined ? 'bold' : '' }"
    @click.prevent="refine(value)"
  >
    {{ value.name }}
    ({{ value.count }})
  </a>
</ais-toggle-refinement>

HTML output

Copy 
1
2
3
4
5
6
7

<div class="ais-ToggleRefinement">
  <label class="ais-ToggleRefinement-label">
    <input class="ais-ToggleRefinement-checkbox" type="checkbox" />
    <span class="ais-ToggleRefinement-labelText">Free Shipping</span>
    <span class="ais-ToggleRefinement-count">18,013</span>
  </label>
</div>

Did you find this page helpful?

Vue InstantSearch v3