Create your widgets

Learn how you can create a custom widget for your Vue InstantSearch app.

You can build your own components when the provided ones aren’t sufficient.

If you’re creating a custom InstantSearch widget because you didn’t find a built-in option for your use case, consider opening a feature request to describe what you’re trying to build.

Existing connectors

Sometimes you might want to create a component which uses a piece of data not provided by any of the widgets. You also might want to make a custom component for having access to the data in different places than the template.

You can do this with the createWidgetMixin function exposed by Vue InstantSearch. It works together with the connectors from InstantSearch.js.

1. Connect the menu widget

   Choose the connectMenu connector for this example.

   Vue 3

   <script>
   import { createWidgetMixin } from 'vue-instantsearch/vue3/es';
   import { connectMenu } from 'instantsearch.js/es/connectors';
   
   export default {
     mixins: [createWidgetMixin({ connector: connectMenu })],
   };
   </script>
   

   All information from that connector will then be available to your template as well as your other Vue lifecycle methods (after created). All information will be available on this.state on your instance, and will be null initially (so make sure your code is safe by wrapping usage in the template for example in an v-if="state").

2. Determine widget parameters

   All connectors expect to be passed widget parameters. Since these change over the lifecycle of a component, and are usually passed through props, the widget mixin expects a property widgetParams on the component’s instance. Create it with a computed property, based on props:

   Vue

   export default {
     // ...
     props: {
       attribute: {
         type: String,
         required: true,
       },
     },
     computed: {
       widgetParams() {
         return {
           attribute: this.attribute,
         };
       },
     },
   };
   
3. Filter items by widget state

   Use state here to filter over the items.

   Vue

   export default {
     // ...
     computed: {
       // ...
       items() {
         // Not needed here if you v-if in the template
         // Only labels of three character long allowed
         return this.state.items.filter(item => item.label.length === 3)
       },
     },
   };
   

   This is also possible with the transform-items prop on ais-menu).

   For more information, see UI state.

4. Render menu items in the template

   Vue

   <ul>
     <li v-for="item in items" :key="item.value">
       <button @click="state.refine(item.value)">
         {{ item.label }}
       </button>
     </li>
   </ul>
   

Custom connectors

If you want to make your own connector, you can do that using a function with this signature:

JavaScript

const connector = (renderFn, unmountFn) => (widgetParams = {}) => ({
  init({ instantSearchInstance }) {
    renderFn(
      {
        /* Anything you put here comes in this.state */
      },
      true
    );
  },

  render({ results, instantSearchInstance }) {
    renderFn(
      {
        /* Anything you put here comes in this.state */
      },
      false
    );
  },

  dispose() {
    unmountFn();
  },
});

That lets you access the lowest level of abstraction, including the Algolia search helper.