🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
UI libraries / Vue InstantSearch / Widgets

ais-toggle-refinement

Signature 
<ais-toggle-refinement
  attribute="string"
  label="string"
  // Optional parameters
  :on="string|number|boolean"
  :off="string|number|boolean"
  :class-names="object"
/>
Import
Copy 
1
2
3
4
5
6
7
8
9

import { AisToggleRefinement } from 'vue-instantsearch';
// Use 'vue-instantsearch/vue3/es' for Vue 3

export default {
  components: {
    AisToggleRefinement
  },
  // ...
};

1. Follow additional steps in Optimize build size to ensure your code is correctly bundled.
2. This imports all the widgets, even the ones you don’t use. Read the Getting started guide for more information.

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

Parameter Description
attribute
type: string
Required

The name of the attribute on which to apply the refinement.

To avoid unexpected behavior, you can’t use the same attribute prop in a different type of widget.
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 you can 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

Parameter Description
default

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

Note that when you implement this slot, none of the other slots will change the output, as the default slot surrounds them.

Scope

  • value: object: the current refinement. It contains name, count and isRefined.
  • canRefine: boolean: whether 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.
Copy 
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

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 v4