ais-toggle-refinement

Lets users toggle a specific filter.

Signature

<ais-toggle-refinement
  attribute="string"
  label="string"
  // Optional parameters
  :on="string | number | boolean"
  :off="string | number | boolean"
  :class-names="object"
/>

Import

Component

To ensure optimal bundle sizes, see Optimize build size.

Vue

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

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

Plugin

This imports all widgets, even the ones you don’t use. For more information, see Get started with Vue InstantSearch.

JavaScript

import Vue from "vue";
import InstantSearch from "vue-instantsearch";
// Use "vue-instantsearch/vue3/es" for Vue 3

Vue.use(InstantSearch);

See this widget in action

Preview this widget and its behavior.

About this widget

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

Examples

Vue

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

Props

attribute · 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.

Vue

<ais-toggle-refinement
  [...]
  attribute="free_shipping"
/>

label · string · required

The label to display for the checkbox.

Vue

<ais-toggle-refinement
  [...]
  label="Free Shipping"
/>

on · string | number | boolean · default: true

The value of the refinement to apply on the attribute when checked.

Vue

<ais-toggle-refinement
  [...]
  :on="true"
/>

off · string | number | boolean

The value of the refinement to apply on the attribute when unchecked.

Vue

<ais-toggle-refinement
  [...]
  :off="false"
/>

class-names · object · default: "{}"

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.

Vue

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

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.

  To learn more, see the insights middleware.

Vue

<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

HTML

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