ais-menu - Algolia

Signature

<ais-menu
  attribute="string"
  // Optional parameters
  :limit="number"
  :show-more="boolean"
  :show-more-limit="number"
  :sort-by="string[] | function"
  :transform-items="function"
  :class-names="object"
/>

Import

Component
Plugin

To ensure optimal bundle sizes, see Optimize build size.

Vue

import { AisMenu } from "vue-instantsearch";
// Use "vue-instantsearch/vue3/es" for Vue 3

export default {
  components: {
    AisMenu
  },
  // ...
};

This imports all widgets, even the ones you don’t use. For more information, see Get started with Vue InstantSearch.

JavaScript

import Vue from "vue";
import InstantSearch from "vue-instantsearch";
// Use "vue-instantsearch/vue3/es" for Vue 3

Vue.use(InstantSearch);

See this widget in action

Preview this widget and its behavior.

The ais-menu widget displays a menu that lets users choose a single value for a specific attribute.

The ais-menu widget uses a hierarchical refinement internally, so it can’t refine values that include the default separator (>). To support these values, use the ais-hierarchical-menu widget instead.

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.

Examples

Vue

<ais-menu attribute="categories" />

Props

attribute

string

required

The name of the attribute in the record.To avoid unexpected behavior, you can’t use the same attribute prop in a different type of widget.

Vue

<ais-menu attribute="categories" />

limit

number

default:10

How many facet values to retrieve. When you enable the show-more feature, this is the number of facet values to display before clicking the “Show more” button.

Vue

<ais-menu
  // [...]
  :limit="20"
/>

show-more

boolean

default:false

Whether to display a button that expands the number of items.

Vue

<ais-menu
  // [...]
  show-more
/>

show-more-limit

number

default:20

Amount of items to show if showing more. Requires show-more to be true.

Vue

<ais-menu
  // [...]
  :show-more-limit="30"
/>

sort-by

string[] | function

How to sort refinements. Must be one or more of the following strings:

"count" (same as "count:desc")
"count:asc"
"count:desc"
"name" (same as "name:asc")
"name:asc"
"name:desc"
"isRefined" (same as "isRefined:asc")
"isRefined:asc"
"isRefined:desc"

It’s also possible to give a function, which receives items two by two, like JavaScript’s Array.sort.If facetOrdering is set for this facet in renderingContent, and no value for sortBy is passed to this widget, facetOrdering is used, and the default order as a fallback.

To prevent creating infinite loops, avoid passing arrays, objects, or functions directly in the template. These values aren’t referentially equal on each render, which causes the widget to re-register every time. Instead, define them in your component’s data option and reference them in the template.

Vue

<ais-menu
  // [...]
  :sort-by="['isRefined', 'count:desc']"
/>

transform-items

function

default:"items => items"

A function that receives the list of items before they are displayed. It should return a new array with the same structure. Use this to transform, filter, or reorder the items.The function also has access to the full results data, including all standard response parameters and parameters from the helper, such as disjunctiveFacetsRefinements.

Vue

<template>
  <!-- ... -->
  <ais-menu
    // [...]
    :transform-items="transformItems"
  />
</template>

<script>
export default {
  methods: {
    transformItems(items) {
      return items.map((item) => ({
        ...item,
        label: item.label.toUpperCase(),
      }));
    },

    /* or, combined with results */
    transformItems(items, { results }) {
      return items.map((item) => ({
        ...item,
        label: item.isRefined
          ? `${item.label} (${results.nbPages} pages)`
          : item.label,
      }));
    },
  },
};
</script>

class-names

object

default:"{}"

The CSS classes you can override:

.ais-Menu. The root element of the widget.
.ais-Menu--noRefinement. The root element of the widget with no refinement.
.ais-Menu-list. The list of all menu items.
.ais-Menu-item. The menu list item.
.ais-Menu-item--selected. The selected menu list item.
.ais-Menu-link. The clickable menu element.
.ais-Menu-label. The label of each item.
.ais-Menu-count. The count of values for each item.
.ais-Menu-showMore. The button used to display more categories.
.ais-Menu-showMore--disabled. The disabled button used to display more categories.

Vue

<ais-menu
  [...]
  :class-names="{
    'ais-Menu': 'MyCustomMenu',
    'ais-Menu-link': 'MyCustomMenuLink',
    // ...
  }"
/>

Customize the UI

default

The slot to override the complete DOM output of the widget.When you implement this slot, none of the other slots will change the output, as the default slot surrounds them.Scope

items: object[]. The values applicable to this menu.
canRefine: boolean. Can the refinement be applied?
canToggleShowMore: boolean. Is show-more possible?
isShowingMore: boolean. Is show-more enabled?
refine: (value: string) => void. The function to select a refinement.
createURL: (value: string) => string. The function to return a link for this refinement.
sendEvent: (eventType: 'click', facetValue: string) => void. The function to send click events.
- The view event is automatically sent when the facets are rendered.
- The click event is automatically sent when refine is called.
- You can learn more about the insights middleware.

Where each item is an object containing:

value: string. The value of the menu item.
label: string. The human-readable value of the menu item.
count: number. The number of results matched after a refinement is applied.
isRefined: boolean. Indicates if the refinement is applied.

Vue

<ais-menu attribute="categories">
  <template
    v-slot="{
      items,
      canToggleShowMore,
      isShowingMore,
      toggleShowMore,
      refine,
      createURL,
      sendEvent,
    }"
  >
    <ul>
      <li v-for="item in items" :key="item.value">
        <a
          :href="createURL(item.value)"
          :style="{ fontWeight: item.isRefined ? 'bold': '' }"
          @click.prevent="refine(item.value)"
        >
          {{item.label}} - {{item.count}}
        </a>
      </li>
      <li>
        <button :disabled="!canToggleShowMore" @click="toggleShowMore">
          {{ isShowingMore ? 'Less' : 'More'}}
        </button>
      </li>
    </ul>
  </template>
</ais-menu>

showMoreLabel

The slot to override the DOM output for the label of the “Show more” button.Scope

isShowingMore: boolean. Is show-more enabled?

Vue

<ais-menu attribute="categories" show-more>
  <template v-slot:showMoreLabel="{ isShowingMore }">
    {{ isShowingMore ? 'Less' : 'More' }}
  </template>
</ais-menu>

HTML output

HTML

<div class="ais-Menu">
  <ul>
    <li>
      <a class="ais-Menu-link">
        <span class="ais-Menu-label">Apple</span>
        <span class="ais-Menu-count">50</span>
      </a>
    </li>
    <!-- more items -->
  </ul>
  <button class="ais-Menu-showMore">Show more</button>
</div>

If SEO is important for your search page, ensure that your custom HTML is optimized for search engines:

Use <a> tags with href attributes to allow search engine bots to follow links.
Use semantic HTML and include structured data when relevant.

For more guidance, see the SEO checklist.

​Import

See this widget in action

​About this widget

​Requirements

​Examples

​Props

​Customize the UI

​HTML output

Import

About this widget

Requirements

Examples

Props

Customize the UI

HTML output