> ## 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-dynamic-widgets

> Shows ordered facets and facet values based on index settings and rules.

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

## 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 { AisDynamicWidgets } from "vue-instantsearch";
    // Use "vue-instantsearch/vue3/es" for Vue 3

    export default {
      components: {
        AisDynamicWidgets,
      },
      // ...
    };
    ```
  </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-dynamic-widgets&selectedStory=simple%20usage" horizontal>
  Preview this widget and its behavior.
</Card>

## About this widget

`ais-dynamic-widgets` is a widget that displays matching widgets,
based on the corresponding index settings and applied index rules.
You can configure the facet merchandising through the corresponding index setting.
To learn more, see [Facet display](/doc/guides/building-search-ui/ui-and-ux-patterns/facet-display/vue).

### Requirements

You must set the attributes for faceting and configure the facet order,
either using the [dashboard](/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting-with-dashboard) or with the API parameters [`attributesForFaceting`](/doc/api-reference/api-parameters/attributesForFaceting) and [`renderingContent`](/doc/api-reference/api-parameters/renderingContent).

All matching widgets mount after the first network request completes.
To avoid a second network request, facets are set to `['*']` and `maxValuesPerFacet` is set to 20 by default.

If this behavior isn't what you want,
it can be overridden using the [`facets`](#param-facets) and [`max-values-per-facet`](#param-max-values-per-facet) parameters.

<Note>
  You must use Vue InstantSearch v3.8.0 or later to use `ais-dynamic-widgets`.
</Note>

## Examples

<CodeGroup>
  ```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>
  ```
</CodeGroup>

## Options

<ParamField body="children" type="Widget[]" required>
  The children of this component will be displayed dynamically based on the result of `facetOrdering`.
  This means that any child needs to have either the "attribute" or "attributes" prop.

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

    ```vue hierarchical 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>
    ```
  </CodeGroup>
</ParamField>

<ParamField body="transform-items" type="function">
  A function to transform the attributes to render,
  or using a different source to determine the attributes to render.

  ```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>
  ```
</ParamField>

<ParamField body="facets" type="['*']|[]" 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.

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

    ```vue no facets theme={"system"}
    <ais-dynamic-widgets
      // ...
      :facets="[]"
    />
    ```
  </CodeGroup>
</ParamField>

<ParamField body="max-values-per-facet" type="number" default={20}>
  The default number of facet values to request.
  It's recommended to have this value at least as high as the highest limit and showMoreLimit of dynamic widgets,
  as this will prevent a second network request once that widget mounts.

  To avoid pinned items not showing in the result,
  make sure you choose a `max-values-per-facet` at least as high as all the most pinned items you have.

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