> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ais-menu

> Shows a menu for refining search results based on a selected facet value.

```vue Signature theme={"system"}
<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

<Tabs>
  <Tab title="Component">
    To ensure optimal bundle sizes,
    see [Optimize build size](/doc/guides/building-search-ui/going-further/improve-performance/vue#optimize-build-size).

    ```js Vue icon=code theme={"system"}
    import { AisMenu } from "vue-instantsearch";
    // Use "vue-instantsearch/vue3/es" for Vue 3

    export default {
      components: {
        AisMenu
      },
      // ...
    };
    ```
  </Tab>

  <Tab title="Plugin">
    This imports all widgets, even the ones you don't use.
    For more information, see [Get started with Vue InstantSearch](/doc/guides/building-search-ui/getting-started/vue).

    ```js JavaScript icon="code" theme={"system"}
    import Vue from "vue";
    import InstantSearch from "vue-instantsearch";
    // Use "vue-instantsearch/vue3/es" for Vue 3

    Vue.use(InstantSearch);
    ```
  </Tab>
</Tabs>

<Card title="See this widget in action" icon="monitor-play" href="https://instantsearchjs.netlify.app/stories/vue/?selectedKind=ais-menu" horizontal>
  Preview this widget and its behavior.
</Card>

## About this widget

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

<Note>
  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`](/doc/api-reference/widgets/hierarchical-menu/vue) widget instead.
</Note>

### Requirements

The [`attribute`](#param-attribute) provided to the widget must be in attributes for faceting,
either on the [dashboard](/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting-with-dashboard) or using the [`attributesForFaceting`](/doc/api-reference/api-parameters/attributesForFaceting) parameter with the API.

## Examples

```vue Vue icon=code theme={"system"}
<ais-menu attribute="categories" />
```

## Props

<ParamField body="attribute" type="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 Vue icon=code theme={"system"}
  <ais-menu attribute="categories" />
  ```
</ParamField>

<ParamField body="limit" type="number" default={10}>
  How many facet values to retrieve.
  When you enable the [`show-more`](#param-show-more) feature,
  this is the number of facet values to display before clicking the "Show more" button.

  ```vue Vue icon=code theme={"system"}
  <ais-menu
    // [...]
    :limit="20"
  />
  ```
</ParamField>

<ParamField body="show-more" type="boolean" default={false}>
  Whether to display a button that expands the number of items.

  ```vue Vue icon=code theme={"system"}
  <ais-menu
    // [...]
    show-more
  />
  ```
</ParamField>

<ParamField body="show-more-limit" type="number" default={20}>
  Amount of items to show if showing more.
  Requires [`show-more`](#param-show-more) to be `true`.

  ```vue Vue icon=code theme={"system"}
  <ais-menu
    // [...]
    :show-more-limit="30"
  />
  ```
</ParamField>

<ParamField body="sort-by" type="string[] | function" default="Uses facetOrdering if set, ['name:asc', 'count:desc']">
  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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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.

  <Note>
    To [prevent creating infinite loops](https://support.algolia.com/hc/en-us/articles/4406511683217-Vue-InstantSearch-How-do-I-prevent-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.
  </Note>

  ```vue Vue icon=code theme={"system"}
  <ais-menu
    // [...]
    :sort-by="['isRefined', 'count:desc']"
  />
  ```
</ParamField>

<ParamField body="transform-items" type="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](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/)
  and [parameters from the helper](https://community.algolia.com/algoliasearch-helper-js/reference.html#query-parameters),
  such as `disjunctiveFacetsRefinements`.

  ```vue Vue icon=code theme={"system"}
  <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>
  ```
</ParamField>

<ParamField body="class-names" type="object" default="{}">
  The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/vue#style-your-widgets):

  * `.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 Vue icon=code theme={"system"}
  <ais-menu
    [...]
    :class-names="{
      'ais-Menu': 'MyCustomMenu',
      'ais-Menu-link': 'MyCustomMenuLink',
      // ...
    }"
  />
  ```
</ParamField>

## Customize the UI

<ParamField body="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](#param-show-more) possible?
  * `isShowingMore: boolean`. Is [show-more](#param-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`](/doc/api-reference/widgets/insights/vue) 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 Vue icon=code theme={"system"}
  <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>
  ```
</ParamField>

<ParamField body="showMoreLabel">
  The slot to override the DOM output for the label of the "Show more" button.

  **Scope**

  * `isShowingMore: boolean`. Is [show-more](#param-show-more) enabled?

  ```vue Vue icon=code theme={"system"}
  <ais-menu attribute="categories" show-more>
    <template v-slot:showMoreLabel="{ isShowingMore }">
      {{ isShowingMore ? 'Less' : 'More' }}
    </template>
  </ais-menu>
  ```
</ParamField>

## HTML output

```html HTML icon=code-xml theme={"system"}
<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>
```

<Note>
  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](https://developers.google.com/search/docs/appearance/structured-data) when relevant.

  For more guidance, see the [SEO checklist](/doc/guides/building-search-ui/resources/seo/js).
</Note>