API Reference / Vue InstantSearch Widgets / ais-toggle-refinement
Apr. 11, 2019

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"
/>

About this widget

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

Examples

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.

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

The label to display for the checkbox.

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.

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.

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.
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.
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 }"
    :href="createURL(value)"
    :style="{ fontWeight: value.isRefined ? 'bold' : '' }"
    @click.prevent="refine(value)"
  >
    {{ value.name }}
    ({{ value.count }})
  </a>
</ais-toggle-refinement>

HTML output

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?