API Reference / Vue InstantSearch Widgets / ais-current-refinements
Apr. 24, 2019

ais-current-refinements

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

included-attributes
type: string[]
Optional

The attributes to include in the widget (all by default). Cannot 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. Cannot 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: x => x
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.
Copy
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.
Copy
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: string) => 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
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

<ais-current-refinements>
  <ul slot-scope="{ items, createURL }">
    <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)"
          >
            {{ item.label }} X
          </a>
        </li>
      </ul>
    </li>
  </ul>
</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 wihtout 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.
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 slot="item" slot-scope="{ 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>
  <a
    slot="refinement"
    slot-scope="{ refinement, refine, createURL }"
    :href="createURL(refinement)"
    @click.prevent="refine(refinement)"
  >
    {{ refinement.label }} X
  </a>
</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 v2