API Reference / Vue InstantSearch Widgets / 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: string) => void: the function to call with the provided value to update the refinement.
  • createURL: (value: string) => void: the function to generate a link 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.
1
2
3
4
5
6
7
8
9
10
11
12
<ais-toggle-refinement attribute="free_shipping" label="Free Shipping">
  <template v-slot="{ value, refine, createURL, sendEvent }">
    <a
      :href="createURL(value)"
      :style="{ fontWeight: value.isRefined ? 'bold' : '' }"
      @click.prevent="refine(value)"
    >
      {{ value.name }}
      ({{ value.count }})
    </a>
  </template>
</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?