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

# DynamicWidgets

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

<Note>
  This is the **React InstantSearch v7** documentation.
  If you're upgrading from v6, see the [upgrade guide](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-v6-to-react-instantsearch-v7).
  If you were using React InstantSearch Hooks,
  this v7 documentation applies—just check for [necessary changes](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-hooks-to-react-instantsearch-v7).
  To continue using v6, you can find the [archived documentation](https://algolia.com/old-docs/deprecated/instantsearch/react/v6/api-reference/instantsearch/).
</Note>

```tsx Signature theme={"system"}
<DynamicWidgets
  // Optional parameters
  transformItems={function}
  fallbackComponent={ReactNode}
  facets={['*'] | []}
  maxValuesPerFacet={number}
>
  {children}
</DynamicWidgets>
```

## Import

```jsx JavaScript icon=code theme={"system"}
import { DynamicWidgets } from "react-instantsearch";
```

<Card title="See this widget in action" icon="monitor-play" href="https://instantsearchjs.netlify.app/stories/?path=/story/basics-dynamicwidgets--default" horizontal>
  Preview this widget and its behavior.
</Card>

## About this widget

`<DynamicWidgets>` 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/react).

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.

You can override these settings with the [`facets`](#param-facets) and [`maxValuesPerFacet`](/doc/api-reference/widgets/dynamic-facets/react#param-max-values-per-facet) parameters.

When server-rendering, InstantSearch will render in two passes,
ensuring that the refinements seen in your UI are correct.

<Tip>You can also create your own UI with [`useDynamicWidgets`](#hook).</Tip>

### 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).

## Examples

```jsx JavaScript icon=code theme={"system"}
import { InstantSearch, DynamicWidgets } from "react-instantsearch";

function App(props) {
  return (
    <InstantSearch {...props}>
      <DynamicWidgets>
        <HierarchicalMenu
          attributes={["hierarchical.lvl0", "hierarchical.lvl1"]}
        />
        <RefinementList attribute="brand" />
      </DynamicWidgets>
    </InstantSearch>
  );
}
```

## Props

<ParamField body="children" type="React.ReactNode">
  The children of this component are displayed dynamically based on the result of `facetOrdering`.

  Any child needs to have either an `attribute` or `attributes` prop.

  <CodeGroup>
    ```jsx Direct children theme={"system"}
    <DynamicWidgets>
      <HierarchicalMenu attributes={["hierarchical.lvl0", "hierarchical.lvl1"]} />
      <RefinementList attribute="brand" />
    </DynamicWidgets>;
    ```

    ```jsx Children in Panel theme={"system"}
    <DynamicWidgets>
      <Panel header="Categories">
        <HierarchicalMenu attributes={["hierarchical.lvl0", "hierarchical.lvl1"]} />
      </Panel>
      <Panel header="Brands">
        <RefinementList attribute="brand" />
      </Panel>
    </DynamicWidgets>;
    ```
  </CodeGroup>
</ParamField>

<ParamField body="fallbackComponent" type="React.ReactNode">
  Component used if none of the children matches the `attribute` or `attributes[0]` prop.

  <CodeGroup>
    ```jsx App.js theme={"system"}
    <DynamicWidgets fallbackComponent={RefinementList} />;
    ```

    ```jsx RefinementList.js theme={"system"}
    export function RefinementList(props) {
      const { items, refine } = useRefinementList(props);

      return <>{/* Your JSX */}</>;
    }
    ```
  </CodeGroup>
</ParamField>

<ParamField body="transformItems" type="(items: string[], metadata: { results: SearchResults }) => string[]">
  A function to transform the attributes to render, or using a different source to determine the attributes to render.

  <CodeGroup>
    ```jsx JavaScript theme={"system"}
    const transformItems = (items, { results }) => {
      return results.userData.customOrdering;
    };

    function Search() {
      return <DynamicWidgets transformItems={transformItems} />;
    }
    ```

    ```tsx TypeScript theme={"system"}
    import type { DynamicWidgetsProps } from "react-instantsearch";

    const transformItems: DynamicWidgetsProps["transformItems"] = (
      items,
      { results },
    ) => {
      return results.userData.customOrdering;
    };

    function Search() {
      return <DynamicWidgets transformItems={transformItems} />;
    }
    ```
  </CodeGroup>
</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 rendered.

  <CodeGroup>
    ```jsx All facets theme={"system"}
    <DynamicWidgets facets={["*"]} />;
    ```

    ```jsx No facets theme={"system"}
    <DynamicWidgets facets={[]} />;
    ```
  </CodeGroup>
</ParamField>

<ParamField body="maxValuesPerFacet" type="number" default={20}>
  The default number of facet values to request.

  To prevent an additional network request when a widget mounts,
  it's recommended to set this value as high as the highest `limit` and `showMoreLimit` of the dynamic widgets.
  To avoid pinned items not showing in the result,
  make sure you choose a `maxValuesPerFacet` as high as all the most pinned items you have.

  ```jsx JavaScript icon=code theme={"system"}
  <DynamicWidgets maxValuesPerFacet={500} />;
  ```
</ParamField>

## Hook

React InstantSearch let you create your own UI for the `<DynamicWidgets>` widget with `useDynamicWidgets`.
Hooks provide APIs to access the widget state and interact with InstantSearch.

The `useDynamicWidgets` Hook accepts [parameters](#parameters) and returns [APIs](#hook).
It must be used inside the [`<InstantSearch>`](/doc/api-reference/widgets/instantsearch/react) component.

### Usage

First, create your React component:

```jsx JavaScript icon=code theme={"system"}
import { useDynamicWidgets } from "react-instantsearch";

function CustomDynamicWidgets(props) {
  const { attributesToRender } = useDynamicWidgets(props);

  return <>{/* Your JSX */}</>;
}
```

Then, render the widget:

```jsx JavaScript icon=code theme={"system"}
<CustomDynamicWidgets {...props} />;
```

### Parameters

Hooks accept parameters. You can either pass them manually or forward props from a custom component.

<Note>
  When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders.
  Use [`useCallback()`](https://reactjs.org/docs/hooks-reference.html#usecallback) for memoization.
  Arrays and objects are automatically memoized.
</Note>

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

  <CodeGroup>
    ```jsx JavaScript theme={"system"}
    const transformItems = (items, { results }) => {
      return results.userData.customOrdering;
    };

    function DynamicWidgets() {
      const dynamicWidgetsApi = useDynamicWidgets({ transformItems });

      return <>{/* Your JSX */}</>;
    }
    ```

    ```tsx TypeScript theme={"system"}
    import type { UseDynamicWidgetsProps } from "react-instantsearch";

    const transformItems: UseDynamicWidgetsProps["transformItems"] = (
      items,
      { results },
    ) => {
      return results.userData.customOrdering;
    };

    function DynamicWidgets() {
      const dynamicWidgetsApi = useDynamicWidgets({ transformItems });

      return <>{/* Your JSX */}</>;
    }
    ```
  </CodeGroup>
</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>
    ```jsx Default theme={"system"}
    function DynamicWidgets() {
      const dynamicWidgetsApi = useDynamicWidgets({
        facets: ["*"],
      });

      return <>{/* Your JSX */}</>;
    }
    ```

    ```jsx No facets theme={"system"}
    function DynamicWidgets() {
      const dynamicWidgetsApi = useDynamicWidgets({
        facets: [],
      });

      return <>{/* Your JSX */}</>;
    }
    ```
  </CodeGroup>
</ParamField>

<ParamField body="maxValuesPerFacet" 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 prevents a second network request once that widget mounts.

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

  ```jsx JavaScript icon=code theme={"system"}
  function DynamicWidgets() {
    const dynamicWidgetsApi = useDynamicWidgets({
      maxValuesPerFacet: 500,
    });

    return <>{/* Your JSX */}</>;
  }
  ```
</ParamField>

### APIs

Hooks return APIs, such as state and functions. You can use them to build your UI and interact with React InstantSearch.

<ParamField body="attributesToRender" type="string[]">
  The list of refinement values to display returned from the Algolia API.

  ```jsx JavaScript icon=code theme={"system"}
  function DynamicWidgets(props) {
    const { attributesToRender } = useDynamicWidgets(props);

    return attributesToRender.map((attribute) => (
      <RefinementList key={attribute} attribute={attribute} />
    ));
  }
  ```
</ParamField>

### Example

<CodeGroup>
  ```jsx JavaScript theme={"system"}
  import { RefinementList, useDynamicWidgets } from "react-instantsearch";

  function CustomDynamicWidgets(props) {
    const { attributesToRender } = useDynamicWidgets(props);

    return attributesToRender.map((attribute) => (
      <RefinementList key={attribute} attribute={attribute} />
    ));
  }
  ```

  ```tsx TypeScript theme={"system"}
  import {
    RefinementList,
    useDynamicWidgets,
    UseDynamicWidgetsProps,
  } from "react-instantsearch";

  function CustomDynamicWidgets(props: UseDynamicWidgetsProps) {
    const { attributesToRender } = useDynamicWidgets(props);

    return attributesToRender.map((attribute) => (
      <RefinementList key={attribute} attribute={attribute} />
    ));
  }
  ```
</CodeGroup>