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

# Dynamic widgets

> Renders matching refinement widgets in the facet order returned by Algolia.

```vue Signature theme={"system"}
<ais-dynamic-widgets
  // Optional parameters
  transform-items="function"
  facets="['*']|[]"
  max-values-per-facet="number"
>
  children
</ais-dynamic-widgets>
```

## Import

> [tab] Component
>
> To ensure optimal bundle sizes,
> see [Optimize build size](https://www.algolia.com/doc/guides/building-search-ui/going-further/improve-performance/vue.md#optimize-build-size).
>
> ```js Vue icon=code theme={"system"}
> import { AisDynamicWidgets } from "vue-instantsearch";
> // Use "vue-instantsearch/vue3/es" for Vue 3
>
> export default {
>   components: {
>     AisDynamicWidgets,
>   },
>   // ...
> };
> ```

> [tab] Plugin
>
> This imports all widgets, even the ones you don't use.
> For more information, see [Get started with Vue InstantSearch](https://www.algolia.com/doc/guides/building-search-ui/getting-started/vue.md).
>
> ```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);
> ```

> [card] [See this widget in action](https://instantsearchjs.netlify.app/examples/js/showcase/?view=instantsearch\&flavor=vue)
>
> Preview this widget and its behavior.

## About this widget

This widget displays matching refinement widgets in the order provided by
[`renderingContent.facetOrdering`](https://www.algolia.com/doc/api-reference/api-parameters/renderingContent#param-facet-ordering)
in the search response.

Configure the order with
[facet display](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/facet-display/vue.md)
, override it with
[Algolia Rules](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview)
, or generate it automatically with
[Dynamic Facets](https://www.algolia.com/doc/guides/algolia-ai/dynamic-facets.md)
. Dynamic Facets orders facets and facet values based on recent search
data.

### Requirements

Declare each facet attribute in [`attributesForFaceting`](https://www.algolia.com/doc/api-reference/api-parameters/attributesForFaceting).

Configure the facet order in the [Algolia dashboard](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting-with-dashboard.md) or
with [`renderingContent.facetOrdering`](https://www.algolia.com/doc/api-reference/api-parameters/renderingContent#param-facet-ordering).

By default, `<ais-dynamic-widgets>` requests all facets and up to 20 values per facet.
These defaults help avoid another request after matching widgets mount.

Override the defaults with [`facets`](#param-facets) and [`max-values-per-facet`](#param-max-values-per-facet).

> [!NOTE]
>
> `<ais-dynamic-widgets>` requires Vue InstantSearch 3.8.0 or later.

## Examples

```vue Default theme={"system"}
<ais-dynamic-widgets>
  <ais-refinement-list attribute="brand" />
  <ais-panel>
    <ais-menu attribute="categories" />
  </ais-panel>
  <ais-hierarchical-menu :attributes="['categories']" />
</ais-dynamic-widgets>
```

```vue Multiple requests theme={"system"}
<ais-dynamic-widgets :facets="[]">
  <ais-refinement-list attribute="brand" />
  <ais-panel>
    <ais-menu attribute="categories" />
  </ais-panel>
  <ais-hierarchical-menu :attributes="['categories']" />
</ais-dynamic-widgets>
```

## Options

**children** `Widget[]` *required*

The refinement widgets to render in the order specified by [`renderingContent.facetOrdering`](https://www.algolia.com/doc/api-reference/api-parameters/renderingContent#param-facet-ordering).

Each top-level child must resolve to one unique facet attribute.
Define an `attribute` prop for single-attribute widgets or an `attributes` prop for hierarchical widgets.

```vue Widget theme={"system"}
<ais-dynamic-widgets>
  <ais-refinement-list attribute="brand" />
</ais-dynamic-widgets>
```

```vue Hierarchical menu theme={"system"}
<ais-dynamic-widgets>
  <ais-hierarchical-menu :attributes="['categories']" />
</ais-dynamic-widgets>
```

```vue Panel theme={"system"}
<ais-dynamic-widgets>
  <ais-panel>
    <ais-menu attribute="categories" />
  </ais-panel>
</ais-dynamic-widgets>
```

```vue Custom widget theme={"system"}
<ais-dynamic-widgets>
  <my-custom-widget attribute="brand" />
</ais-dynamic-widgets>
```

**transform-items** `function`

Transforms the facet attributes before rendering.

The second argument contains the search results, which you can use to derive a different attribute list.

The function receives the ordered facet attributes from [`renderingContent.facetOrdering.facets.order`](https://www.algolia.com/doc/api-reference/api-parameters/renderingContent#param-facets-order) and returns an array.

```vue Vue icon=code theme={"system"}
<template>
  <ais-dynamic-widgets
    :transform-items="transformItems"
  >
    <!-- ... -->
  </ais-dynamic-widgets>
</template>

<script>
export default {
  methods: {
    transformItems(items, { results }) {
      return items;
    }
  }
}
</script>
```

**facets** `['*']|[]` (default: \['\*'])

The facets to apply before dynamic widgets get mounted.
Setting the value to `['*']` will request all facets and avoid an additional network request once the widgets are added.

```vue Default theme={"system"}
<ais-dynamic-widgets
  :facets="['*']"
/>
```

```vue No facets theme={"system"}
<ais-dynamic-widgets
  :facets="[]"
/>
```

**max-values-per-facet** `number` (default: 20)

The maximum number of values to request for each facet.

Set this value to at least the highest `limit` or `show-more-limit` used by a dynamic widget.
This helps avoid an additional request after the widget mounts.

Set `max-values-per-facet` to at least the largest number of pinned values configured for any facet.
Otherwise, some pinned facet values might not appear.

```vue Vue icon=code theme={"system"}
<ais-dynamic-widgets
  // ...
  :max-values-per-facet="500"
/>
```
