> ## 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.
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
FlavorSwitcher requires at least one option.
;
}
const selected = options.find(option => option.value === current) ?? options[0];
return ;
};
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/).
```tsx Signature theme={"system"}
{children}
```
## Import
```jsx JavaScript icon=code theme={"system"}
import { DynamicWidgets } from "react-instantsearch";
```
Preview this widget and its behavior.
## About this widget
`` 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.
You can also create your own UI with [`useDynamicWidgets`](#hook).
### 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 (
);
}
```
## Props
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.
```jsx Direct children theme={"system"}
;
```
```jsx Children in Panel theme={"system"}
;
```
Component used if none of the children matches the `attribute` or `attributes[0]` prop.
```jsx App.js theme={"system"}
;
```
```jsx RefinementList.js theme={"system"}
export function RefinementList(props) {
const { items, refine } = useRefinementList(props);
return <>{/* Your JSX */};
}
```
A function to transform the attributes to render, or using a different source to determine the attributes to render.
```jsx JavaScript theme={"system"}
const transformItems = (items, { results }) => {
return results.userData.customOrdering;
};
function Search() {
return ;
}
```
```tsx TypeScript theme={"system"}
import type { DynamicWidgetsProps } from "react-instantsearch";
const transformItems: DynamicWidgetsProps["transformItems"] = (
items,
{ results },
) => {
return results.userData.customOrdering;
};
function Search() {
return ;
}
```
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.
```jsx All facets theme={"system"}
;
```
```jsx No facets theme={"system"}
;
```
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"}
;
```
## Hook
React InstantSearch let you create your own UI for the `` 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 [``](/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"}
;
```
### Parameters
Hooks accept parameters. You can either pass them manually or forward props from a custom component.
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.
A function to transform the attributes to render,
or using a different source to determine the attributes to render.
```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 */};
}
```
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.
```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 */};
}
```
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 */};
}
```
### APIs
Hooks return APIs, such as state and functions. You can use them to build your UI and interact with React InstantSearch.
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) => (
));
}
```
### Example
```jsx JavaScript theme={"system"}
import { RefinementList, useDynamicWidgets } from "react-instantsearch";
function CustomDynamicWidgets(props) {
const { attributesToRender } = useDynamicWidgets(props);
return attributesToRender.map((attribute) => (
));
}
```
```tsx TypeScript theme={"system"}
import {
RefinementList,
useDynamicWidgets,
UseDynamicWidgetsProps,
} from "react-instantsearch";
function CustomDynamicWidgets(props: UseDynamicWidgetsProps) {
const { attributesToRender } = useDynamicWidgets(props);
return attributesToRender.map((attribute) => (
));
}
```