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

ais-current-refinements

Signature 
<ais-current-refinements
  // Optional parameters
  :included-attributes="string[]"
  :excluded-attributes="string[]"
  :transform-items="function"
  :class-names="object"
/>
Import
Copy 
1
2
3
4
5
6
7
8
9

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

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

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-current-refinements widget displays a list of refinements applied to the search.

Examples

Copy 
1

<ais-current-refinements />

Props

Parameter Description
included-attributes
type: string[]
Optional

The attributes to include in the widget (all by default). Can’t be used with excluded-attributes. In the example below, only the categories attribute is included in the widget.
Copy 
1
2
3

<ais-current-refinements
  :included-attributes="['categories']"
/>
excluded-attributes
type: string[]
default: ["query"]
Optional

The attributes to exclude from the widget. Can’t be used with included-attributes. In the example below, the brand attribute is excluded from the widget.
Copy 
1
2
3

<ais-current-refinements
  :excluded-attributes="['brand']"
/>
transform-items
type: function
default: items => items
Optional

Receives the items and is called before displaying them. Should return a new array with the same shape as the original array. Useful for transforming, removing, or reordering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).

When using an array, take steps to avoid creating infinite loops. When you use an array as a prop, it causes the widget to re-register on every render, and this can sometimes cause these infinite loops.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

<template>
  <!-- ... -->
  <ais-current-refinements :transform-items="transformItems" />
</template>

<script>
  export default {
    methods: {
      transformItems(items) {
        return items.filter(item => item.attribute !== 'brand');
      },

      /* or, combined with results */
      transformItems(items, { results }) {
        return results.nbHits === 0
          ? items
          : items.filter(item => item.attribute !== 'brand');
      },
    },
  };
</script>
class-names
type: object
default: {}
Optional

The CSS classes you can override:

  • ais-CurrentRefinements: the root element of the widget.
  • ais-CurrentRefinements--noRefinement: the root element of the widget without refinement.
  • ais-CurrentRefinements-list: the list of refined items.
  • ais-CurrentRefinements-item: the item of the refined items list.
  • ais-CurrentRefinements-label: the label of the refined item.
  • ais-CurrentRefinements-delete: the delete button of each item.
Copy 
1
2
3
4
5
6
7

<ais-current-refinements
  :class-names="{
    'ais-CurrentRefinements': 'MyCustomCurrentRefinements',
    'ais-CurrentRefinements-list': 'MyCustomCurrentRefinementsList',
    // ...
  }"
/>

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

  • items: object[]: the refinements currently applied to the search.
  • createURL: (value: object) => string: the function to return a link for the search without this refinement.

Where an item is an object containing:

  • indexName: string: the index name on which the refinement is applied.
  • indexId: string: the index id on which the refinement is applied.
  • attribute: string: the name of the attribute with which the refinement is applied. The value is used as the key.
  • label: string: the name of the attribute with which the refinement is applied. The label is used as the the display value.
  • refine: (value: object) => void: the function to clear a refinement.
  • refinements: object[] each of the individual refinements for this attribute.

Where each refinement is an object containing:

  • type: string: can be "facet", "exclude", "disjunctive", "hierarchical", "numeric" or "query".
  • attribute: string: the name of the attribute where the refinement is applied. The value is used as the key.
  • label: string: the name of the attribute with which the refinement is applied. The label is used as the the display value.
  • value: any: actual value for this refinement
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

<ais-current-refinements>
  <template v-slot="{ items, createURL }">
    <ul>
      <li v-for="item in items" :key="item.attribute">
        {{ item.label }}:
        <ul>
          <li
            v-for="refinement in item.refinements"
            :key="[
              refinement.attribute,
              refinement.type,
              refinement.value,
              refinement.operator
            ].join(':')"
          >
            <a
              :href="createURL(refinement)"
              @click.prevent="item.refine(refinement)"
            >
              {{ refinement.label }} X
            </a>
          </li>
        </ul>
      </li>
    </ul>
  </template>
</ais-current-refinements>
item

The slot to override the DOM output of an item.

Scope

  • item: object: one attribute with refinements.
  • refine: (value: string) => void: the function to clear a refinement.
  • createURL: (value: string) => void: the function to return a link for the search without this refinement.

Where item is an object containing:

  • indexName: string: the index name on which the refinement is applied.
  • indexId: string: the index id on which the refinement is applied.
  • attribute: string: the name of the attribute with which the refinement is applied. The value is used as the key.
  • label: string: the name of the attribute with which the refinement is applied. The label is used as the the display value.
  • refine: (value: object) => void: the function to clear a refinement.
  • refinements: object[] each of the individual refinements for this attribute.

Where each refinement is an object containing:

  • type: string: can be "facet", "exclude", "disjunctive", "hierarchical", "numeric" or "query".
  • attribute: string: the name of the attribute with which the refinement is applied. The value is used as the key.
  • label: string: the name of the attribute with which the refinement is applied. The label is used as the the display value.
  • value: any: the actual value for this refinement.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

<ais-current-refinements>
  <template v-slot:item="{ item, refine, createURL }">
    {{ item.label }}:
    <ul>
      <li
        v-for="refinement in item.refinements"
        :key="[
          refinement.attribute,
          refinement.type,
          refinement.value,
          refinement.operator
        ].join(':')"
      >
        <a
          :href="createURL(refinement)"
          @click.prevent="refine(refinement)"
        >
          {{ refinement.label }} X
        </a>
      </li>
    </ul>
  </template>
</ais-current-refinements>
refinement

The slot to override the DOM output of a single refinement.

Scope

  • refinement: object: one item of the list of refinements.
  • refine: (value: string) => void: the function to clear a refinement.
  • createURL: (value: string) => void: the function to return a link for the search without this refinement.

Where refinement is an object containing:

  • type: string: can be "facet", "exclude", "disjunctive", "hierarchical", "numeric" or "query".
  • attribute: string: the name of the attribute where the refinement is applied. The value is used as the key.
  • label: string: the name of the attribute with which the refinement is applied. The label is used as the the display value.
  • value: any: the actual value for this refinement.
Copy 
1
2
3
4
5
6
7
8
9
10

<ais-current-refinements>
  <template v-slot:refinement="{ refinement, refine, createURL }">
    <a
      :href="createURL(refinement)"
      @click.prevent="refine(refinement)"
    >
      {{ refinement.label }} X
    </a>
  </template>
</ais-current-refinements>

HTML output

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

<div class="ais-CurrentRefinements">
  <ul class="ais-CurrentRefinements-list">
    <li class="ais-CurrentRefinements-itemt">
      <span class="ais-CurrentRefinements-label">
        Category:
      </span>
      <span class="ais-CurrentRefinements-category">
        <span class="ais-CurrentRefinements-categoryLabel">
          Movies & TV Shows
        </span>
        <button class="ais-CurrentRefinements-delete">✕</button>
      </span>
      <span class="ais-CurrentRefinements-category">
        <span class="ais-CurrentRefinements-categoryLabel">
          Others
        </span>
        <button class="ais-CurrentRefinements-delete">✕</button>
      </span>
    </li>
    <li class="ais-CurrentRefinements-item">
      <span class="ais-CurrentRefinements-label">
        Brand:
      </span>
      <span class="ais-CurrentRefinements-category">
        <span class="ais-CurrentRefinements-categoryLabel">
          Algolia
        </span>
        <button class="ais-CurrentRefinements-delete">✕</button>
      </span>
    </li>
  </ul>
</div>
Did you find this page helpful?
Vue InstantSearch v4