Customize existing widgets

This demo is working example of a menu widget rendered as a select HTML element.

The code that uses the default slots to extend the menu widget can be found in src/components/MenuSelect.vue.

This code has been specifically created for Vue 2. Some modifications may be required for it to work correctly in Vue 3.

Highlight and snippet your search results

Search helps users understand what they’re seeing in the results. When users run a , they should be able to tell why a result matches. Algolia highlights the matched text in each result. Algolia can also generate snippets: short excerpts from longer text, truncated to a fixed length around the match. Highlighting is based on the results and you need to customize the ais-hits widget to use the Highlighter. The ais-highlight and the ais-snippet widgets take two props:

attribute: the path to the highlighted attribute of the hit (which can be either a string or an array of strings)
hit: a single result object

Usage notes

Use the ais-highlight widget when you want to display the regular value of an attribute.
Use the ais-snippet widget when you want to display the snippet version of an attribute. To use this widget, the attribute name passed to the attribute prop must be present in “Attributes to snippet” on the Algolia dashboard or configured as attributesToSnippet with a set settings call to the Algolia API.

Example

This example uses the item slot of the Hit widget. In the results the name field is highlighted. These examples use the mark tag to highlight. This is a tag specially made for highlighting pieces of text.

Vue

<ais-hits :escape-HTML="true">
  <template v-slot:item="{ item }">
    <h2>
      <ais-highlight
        attribute="name"
        :hit="item"
        highlightedTagName="mark"
      />
    </h2>
    <p>
      <ais-snippet
        attribute="description"
        :hit="item"
        highlightedTagName="mark"
      />
    </p>
  </template>
</ais-hits>
<ais-configure
  :attributesToSnippet="['description']"
  snippetEllipsisText="[…]"
/>

Style your widgets

All Vue InstantSearch widgets use a set of conventional CSS classes compatible with the InstantSearch CSS themes. If you don’t want to use the themes, you can either write your own theme by following the existing classes and customizing the styles, or override the classes to pass yours instead.

Load the InstantSearch theme

Vue InstantSearch doesn’t inject any styles by default but comes with two optional themes: Algolia and Satellite.

From a CDN

The themes are available on jsDelivr. Unminified:

https://cdn.jsdelivr.net/npm/instantsearch.css@8.11.0/themes/reset.css
https://cdn.jsdelivr.net/npm/instantsearch.css@8.11.0/themes/algolia.css
https://cdn.jsdelivr.net/npm/instantsearch.css@8.11.0/themes/satellite.css

Minified:

https://cdn.jsdelivr.net/npm/instantsearch.css@8.11.0/themes/reset-min.css
https://cdn.jsdelivr.net/npm/instantsearch.css@8.11.0/themes/algolia-min.css
https://cdn.jsdelivr.net/npm/instantsearch.css@8.11.0/themes/satellite-min.css

The reset style sheet is included by default in the Satellite theme, so you don’t need to import it separately. Either copy the files into your own app or use a direct link to jsDelivr.

HTML

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/instantsearch.css@8.11.0/themes/satellite-min.css" integrity="sha256-prR7myGMfCpdBy9F+4BbGPIl4b+GL5A9mez2q1mof5w=" crossorigin="anonymous">

Using npm

If your project imports CSS into JavaScript files using build tools, you can install the theme with npm.

npm install instantsearch.css

Then, you can import the theme directly into your app.

JavaScript

import "instantsearch.css/themes/satellite.css";

Translate your widgets

Vue InstantSearch doesn’t have a dedicated API for translating text, but it has slots in every component. When there’s data needed for rendering this is provided too. For example in ais-pagination:

Vue

<ais-pagination>
  <template v-slot:first>first</template>
  <template v-slot:previous>prev</template>
  <template v-slot:item="{value, active}" :style="{color: active ? 'red' : 'green'}">
    {{value.toLocaleString()}}
  </template>
  <template v-slot:next>next</template>
  <template v-slot:last>last</template>
</ais-pagination>

Templating

Vue InstantSearch supports templating with slots. With them you can customize the markup of each sub part of your components. For example in ais-pagination:

Vue

<ais-pagination>
  <template v-slot:first>first</template>
  <template v-slot:previous>prev</template>
  <template v-slot:item="{value, active}" :style="{color: active ? 'red' : 'green'}">
    {{value.toLocaleString()}}
  </template>
  <template v-slot:next>next</template>
  <template v-slot:last>last</template>
</ais-pagination>

Change the list of items in widgets

Vue InstantSearch provides two APIs for manipulating lists:

sortBy, this is the most straightforward API and obviously limited to sorting
transformItems, this is the most flexible solutions but it requires more involvement on your side

The transform-items prop is a function that takes the whole list of items as a parameter and it will expect to receive in return another array of items. Most of the examples in this guide will use this API.

Sorting

Using `sortBy`

Vue

<ais-refinement-list
  attribute="categories"
  :sortBy="['name']"
/>

Using `transformItems`

Vue

<ais-refinement-list
  attribute="categories"
  transformItems="items => items.sort((a,b) => a.value.localeCompare(b.value))"
/>

Filtering

This example filters out items when the count is lower than 150:

Vue

<ais-refinement-list
  attribute="categories"
  transformItems="items => items.filter(item => item.count >= 150)"
/>

Add manual values

By default, the values in a ais-refinement-list or a ais-menu are dynamic. This means that the values are updated with the context of the search. Most of the time this is the expected behavior, but sometimes you may want to have a static list of values that never change. This example, uses a static list of values:

Vue

<template>
<ais-refinement-list
  attribute="categories"
  :transformItems="getStaticValues"
/>

</template>

<script>
// There is a limitation here with our helper/is.js based libraries
// we do not provide values that were refined and that have 0 count
// In this case, this is problematic because a correct implementation should
// keep track of the selected values and implementing in this situation would
// be a lot of code.
export default {
  methods: {
    getStaticValues: (items) => {
      const staticValues = ['Cell Phones', 'Unlocked Cell Phones'];
      return staticValues.map(value => {
        const item = items.find(item => item.label === value);
        return item || {
          label: value,
          value,
          count: 0,
          isRefined: false,
          highlighted: value,
        };
      });
    }
  }
};
</script>

Showing facets that don’t match the current query helps users explore and refine results. Algolia returns only facet values that match the current query. To show non-matching values, add frontend logic. For example, you could cache facet values the first time you receive them. Then, if Algolia returns fewer values than your facet limit, append the cached values. This approach has limitations:

It doesn’t work with search for facet values because Algolia doesn’t return non-matching values. As a result, highlighting doesn’t work for cached values.
You may need to re-apply sorting in the transformItems function because InstantSearch applies its internal sorting before calling the function.

Vue

<template>
  <ais-refinement-list
    :attribute="brandAttribute"
    :transformItems="transformItems"
  />
</template>

<script>
  import { liteClient as algoliasearch } from 'algoliasearch/lite';

  function uniqBy(items, property) {
    const seen = {};

    return items.filter(item => {
      const val = item[property];

      if (seen[val]) {
        return false;
      } else {
        seen[val] = true;
        return true;
      }
    });
  }

  export default {
    mounted() {
      this.searchClient
        .searchForFacetValues([
          {
            indexName: this.indexName,
            params: {
              facetName: this.brandAttribute,
              facetQuery: '',
              maxFacetHits: this.brandLimit,
            },
          },
        ])
        .then(([{ facetHits }]) => {
          this.initialFacets.push(
            ...facetHits.map(facet => ({
              ...facet,
              label: facet.value,
              value: facet.value,
              isRefined: false,
              count: 0,
            }))
          );
        });
    },
    data() {
      return {
        searchClient: algoliasearch(
          'latency',
          '6be0576ff61c053d5f9a3225e2a90f76'
        ),
        initialFacets: [],
        indexName: 'instant_search',
        brandAttribute: 'brand',
        brandLimit: 10,
      };
    },
    methods: {
      transformItems(items) {
        // If Algolia doesn't return enough results, we lose track of a
        // potentially refined facet.
        // For example, if you refine on "Apple", then search for "chromecast",
        // "Apple" is no longer returned, and we don't know that it was selected
        // based on the initial facets.
        // Keep track of the last state to reflect the fact that it
        // was refined in the UI.
        this.initialFacets.forEach((facet, index) => {
          const updatedItem = items.find(item => item.value === facet.value);

          if (updatedItem) {
            this.initialFacets[index] = {
              ...updatedItem,
              count: 0,
            };
          }
        });

        // If a cached facet is already returned by Algolia, we want it to be
        // displayed rather than to display its cached value.
        // You might need to sort the items again here because the internal
        // sorting happens before `transformItems` is called.
        return uniqBy([...items, ...this.initialFacets], 'value').slice(
          0,
          this.brandLimit
        );
      },
    },
  };
</script>

Use the searchable prop to add a search box to supported widgets:

Vue

<ais-refinement-list
  attribute="categories"
  searchable
/>

Apply default value to widgets

A question that comes up frequently is “How to instantiate a ais-refinement-list widget with a pre-selected item?”. For this use case, you can use the ais-configure widget. The following example instantiates a search page with a default query of “apple” and will show a category menu where the item “Cell Phones” is already selected:

Vue

<template>
  <ais-instant-search
    index-name="instant_search"
    :search-client="searchClient"
  >
    <ais-configure
      query="apple"
      :disjunctive-facets-refinements.camel="{ categories: ['Cell Phones'] }"
    />
    <ais-refinement-list attribute="categories"/>
    <ais-search-box />
    <ais-hits />
  </ais-instant-search>
</template>

<!-- You need to instantiate `searchClient` in your script -->

Provide search parameters

Algolia has a wide range of parameters. If one of the parameters you want to use isn’t covered by any widget, then you should use the ais-configure widget. Here’s an example configuring the number of results per page:

Vue

<template>
  <ais-instant-search
    index-name="your_indexName"
    :search-client="searchClient"
  >
    <ais-configure :hits-per-page.camel="5" />
    <ais-search-box />
    <ais-hits />
  </ais-instant-search>
</template>

<!-- You need to instantiate `searchClient` in your script -->

Dynamic update of search parameters

Updating the props of the ais-configure widget will dynamically change the search parameters and will trigger a new search.

Filter your results without widgets

Widgets already provide a lot of different ways to filter your results but sometimes you might have more complicated use cases that require the filters search parameter.

Don’t use filters on a attribute already used with a widget, it will conflict.

Vue

<ais-configure :filters="NOT categories:'Cell Phones'"></ais-configure>

For more information, see Filters and facet filters.

Customize the complete UI of the widgets

Extending Vue InstantSearch widgets is the second layer of the API. Read about the two others possibilities in the “What’s InstantSearch?” guide. Unlike other flavors of InstantSearch, Vue InstantSearch doesn’t provide connectors. Instead, each widget provides a top level slot to allow for complete customization while being able to reuse the logic of the widget.

When to extend widgets?

Extending widgets means being able to redefine the rendering output of an existing widget. For example, if you want to render the Menu widget as an HTML select element, you must extend the Menu widget. Here are some common examples that require the usage of the connectors API:

When you want to display the widgets using another UI library
When you want to have full control on the rendering without having to re-implement business logic
As soon as you hit a feature wall using the default widgets

How widgets are built

Vue InstantSearch widgets have two parts:

Business logic code
Rendering code

The business logic is called connectors. Connectors are provided by InstantSearch.js and their interfaces are exposed through a scope on the default slot.

Connectors render API

The aim is to share as much of a common API between all connectors as possible. Once you know how to use one connector, you can use them all.

Slot scopes

Most of the connectors will use the same naming for properties passed down to the slot.

items[]: array of items to display, for example the brands list of a custom Refinement List. Every extended widget displaying a list gets an items property to the data passed to its render function.
refine(value|item.value): will refine the current suiState of the widget. Examples include: updating the query for a custom SearchBox or selecting a new item in a custom RefinementList.
currentRefinement: currently applied refinement value (usually the call value of refine()).
createURL(value|item.value): will return a full URL you can display for the specific refine value given you are using the routing feature.

An item is an object that you will find in items arrays. The shape of those objects is always the same.

item.value: The underlying precomputed state value to pass to refine or createURL
item.label: The label to display, for example “Samsung”
item.count: The number of hits matching this item
item.isRefined: Is the item currently selected as a filter

Some connectors will have more data than others. Read their API reference to know more. Connectors for every widget are documented in the API reference, for example the ais-menu widget. You can change the complete rendering with the default slot of every widget. Here’s an example of that for ais-menu:

Vue

<ais-menu attribute="categories">
  <template v-slot="{ items, createURL, refine }">
    <ol>
      <li
        v-for="item in items"
        :key="item.value"
      >
        <component :is="item.isRefined ? 'strong' : 'span'">
          <a
            :href="createURL(item.value)"
            @click.prevent="refine(item.value)"
          >
            {{item.label}} - {{item.count}}
          </a>
        </component>
      </li>
    </ol>
  </template>
</ais-menu>

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Customize existing widgets

Highlight and snippet your search results

Usage notes

Example

Style your widgets

Load the InstantSearch theme

From a CDN

Using npm

Translate your widgets

Templating

Change the list of items in widgets

Sorting

Using `sortBy`

Using `transformItems`

Filtering

Add manual values

Display facets with no matches

Search long lists of facet values

Apply default value to widgets

Provide search parameters

Dynamic update of search parameters

Filter your results without widgets

Customize the complete UI of the widgets

When to extend widgets?

How widgets are built

Connectors render API

Slot scopes

Extending widget example

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

​Highlight and snippet your search results

​Usage notes

​Example

​Style your widgets

​Load the InstantSearch theme

​From a CDN

​Using npm

​Translate your widgets

​Templating

​Change the list of items in widgets

​Sorting

​Using sortBy

​Using transformItems

​Filtering

​Add manual values

​Display facets with no matches

​Search long lists of facet values

​Apply default value to widgets

​Provide search parameters

​Dynamic update of search parameters

​Filter your results without widgets

​Customize the complete UI of the widgets

​When to extend widgets?

​How widgets are built

​Connectors render API

​Slot scopes

​Extending widget example

Highlight and snippet your search results

Usage notes

Example

Style your widgets

Load the InstantSearch theme

From a CDN

Using npm

Translate your widgets

Templating

Change the list of items in widgets

Sorting

Using `sortBy`

Using `transformItems`

Filtering

Add manual values

Display facets with no matches

Search long lists of facet values

Apply default value to widgets

Provide search parameters

Dynamic update of search parameters

Filter your results without widgets

Customize the complete UI of the widgets

When to extend widgets?

How widgets are built

Connectors render API

Slot scopes

Extending widget example