ais-refinement-list
<ais-refinement-list attribute="string" // Optional parameters operator="string" :limit="number" :show-more="boolean" :show-more-limit="number" :searchable="boolean" :searchable-placeholder="string" :sort-by="string[]|function" :transform-items="function" :class-names="object" />
1
2
3
4
5
6
7
8
9
import { AisRefinementList } from 'vue-instantsearch';
// Use 'vue-instantsearch/vue3/es' for Vue 3
export default {
components: {
AisRefinementList
},
// ...
};
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.
About this widget
The ais-refinement-list
widget is one of the most common widget you can find in a search UI.
With this widget, users can filter the dataset based on facets.
The widget only displays the most relevant facet values for the current search context. The sort option only affects the facets that are returned by the engine, not which facets are returned.
This widget also implements search for facet values, which is a mini search inside the values of the facets. This makes it easy to deal with uncommon facet values.
Requirements
The attribute
provided to the widget must be in attributes for faceting, either on the dashboard or using the attributesForFaceting
parameter with the API.
If you are using the searchable
prop, you also need to make the attribute searchable using the dashboard or using the searchable
modifier of attributesForFaceting
with the API.
Disappearing facet values
With many facet values, the available options can change depending on the user’s query. The refinement widget displays the most common facet values for a given query.
A user’s chosen value can vanish if they alter the query. This occurs because only the most common facet values are displayed when there are many options. A previously selected value might not appear if it’s uncommon for the new query.
To also show less common values, adjust the maximum number of values with the configure
widget.
It doesn’t change how many items are shown: the limits you set with limit
and show-more-limit
still apply.
Examples
1
<ais-refinement-list attribute="brand" />
Props
attribute
|
type: string
Required
The name of the attribute in the records. To avoid unexpected behavior, you can’t use the same |
||
Copy
|
|||
operator
|
type: string ("or"|"and")
default: "or"
Optional
How to apply refinements.
|
||
Copy
|
|||
limit
|
type: number
default: 10
Optional
How many facet values to retrieve. When you enable the |
||
Copy
|
|||
show-more
|
type: boolean
default: false
Optional
Whether to display a button that expands the number of items. |
||
Copy
|
|||
show-more-limit
|
type: number
default: 20
Optional
The maximum number of displayed items (only used when |
||
Copy
|
|||
searchable
|
type: boolean
default: false
Optional
Adds a search input to let users search for more facet values.
To make this feature work, you need to make the attribute searchable using the dashboard) or using the In some situations, refined facet values might not be present in the data returned by Algolia. |
||
Copy
|
|||
searchable-placeholder
|
type: string
default: "Search here…"
Optional
The value of the search input placeholder. |
||
Copy
|
|||
sort-by
|
type: string[]|function
default: Uses facetOrdering if set, ["isRefined","count:desc","name:asc"]
How to sort refinements. Must be one or more of the following strings:
It’s also possible to give a function, which receives items two by two, like JavaScript’s If In some situations, refined facet values might not be present in the data returned by Algolia. 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
|
|||
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 |
||
Copy
|
|||
class-names
|
type: object
default: {}
Optional
The CSS classes you can override:
|
||
Copy
|
Customize the UI
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
Where each item is an
|
||
Copy
|
|||
item
|
The slot to override the DOM output of an item. Scope
Where an item is an
|
||
Copy
|
|||
showMoreLabel
|
The slot to override the DOM output of the “Show more” button. Scope
|
||
Copy
|
|||
noResults
|
The slot to override the DOM output of the no results placeholder. Scope
|
||
Copy
|
HTML output
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<div class="ais-RefinementList">
<div class="ais-RefinementList-searchBox">
<!-- SearchBox widget here -->
</div>
<ul class="ais-RefinementList-list">
<li class="ais-RefinementList-item ais-RefinementList-item--selected">
<label class="ais-RefinementList-label">
<input class="ais-RefinementList-checkbox" type="checkbox" value="Insignia™" checked />
<span class="ais-RefinementList-labelText">Insignia™</span>
<span class="ais-RefinementList-count">746</span>
</label>
</li>
<li class="ais-RefinementList-item">
<label class="ais-RefinementList-label">
<input class="ais-RefinementList-checkbox" type="checkbox" value="Samsung">
<span class="ais-RefinementList-labelText">Samsung</span>
<span class="ais-RefinementList-count">633</span>
</label>
</li>
</ul>
<button class="ais-RefinementList-showMore">Show more</button>
</div>