API Reference / Vue InstantSearch Widgets / ais-current-refinements

ais-current-refinements

Widget signature
<ais-current-refinements
  // Optional parameters
  :included-attributes="string[]"
  :excluded-attributes="string[]"
  :transform-items="function"
  :class-names="object"
/>

About this widget

The ais-current-refinements widget displays a list of refinements applied to the search.

Examples

1
<ais-current-refinements />

Props

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.

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.

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 mapping over the items to transform, and remove or reorder them.

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<template>
  <!-- ... -->
  <ais-current-refinements :transform-items="transformItems" />
</template>

<script>
  export default {
    methods: {
      transformItems(items) {
        return items.filter(item => item.attribute !== 'brand');
      },
    },
  };
</script>
class-names
type: object
default: {}
Optional

The CSS classes to 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.
1
2
3
4
5
6
7
<ais-current-refinements
  :class-names="{
    'ais-CurrentRefinements': 'MyCustomCurrentRefinements',
    'ais-CurrentRefinements-list': 'MyCustomCurrentRefinementsList',
    // ...
  }"
/>

Customize the UI

default

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

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:

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

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

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?