<DynamicWidgets>
This is the React InstantSearch v7 documentation. React InstantSearch v7 is the latest version of React InstantSearch and the stable version of React InstantSearch Hooks.
If you were using React InstantSearch v6, you can upgrade to v7.
If you were using React InstantSearch Hooks, you can still use the React InstantSearch v7 documentation, but you should check the upgrade guide for necessary changes.
If you want to keep using React InstantSearch v6, you can find the archived documentation.
<DynamicWidgets // Optional parameters transformItems={function} fallbackComponent={ReactNode} facets={['*'] | []} maxValuesPerFacet={number} > {children} </DynamicWidgets>
1
import { DynamicWidgets } from 'react-instantsearch';
About this widget
<DynamicWidgets>
is a widget that displays matching widgets, based on the corresponding settings of the index and may be altered by a Rule.
You can configure the facet merchandising through the corresponding index setting.
Learn how to set up ordering in the facet display guide.
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
and maxValuesPerFacet
parameters.
When server-rendering, InstantSearch will render in two passes, ensuring that the refinements seen on the frontend are correct.
Requirements
You must set the attributes for faceting and configure the facet order, either using the dashboard or with the API parameters attributesForFaceting
and renderingContent
.
You can also create your own UI with
useDynamicWidgets()
.
You must use at least React InstantSearch version 6.16.0 to use <DynamicWidgets>.
Examples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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
children
|
type: React.ReactNode
The children of this component are displayed dynamically based on the result of Any child needs to have either an |
||
Copy
|
|||
fallbackComponent
|
type: React.ReactNode
Optional
Component used if none of the children matches the |
||
Copy
|
|||
transformItems
|
type: (items: string[], metadata: { results: SearchResults }) => string[]
Optional
A function to transform the attributes to render, or using a different source to determine the attributes to render. |
||
Copy
|
|||
facets
|
type: ['*']|[]
default: ['*']
Optional
The facets to apply before dynamic widgets get mounted. Setting the value to |
||
Copy
|
|||
maxValuesPerFacet
|
type: number
default: 20
Optional
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 |
||
Copy
|
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 and returns APIs.
Usage
First, create your React component:
import { useDynamicWidgets } from 'react-instantsearch';
function CustomDynamicWidgets(props) {
const { attributesToRender } = useDynamicWidgets(props);
return <>{/* Your JSX */}</>;
}
Then, render the widget:
<CustomDynamicWidgets {...props} />
Parameters
Hooks accept parameters. You can pass them manually, or forward the props from your custom component.
When you provide a function to Hooks, make sure to pass a stable reference to avoid rendering endlessly (for example, with useCallback()
). Objects and arrays are memoized; you don’t need to stabilize them.
transformItems
|
type: function
Optional
A function to transform the attributes to render, or using a different source to determine the attributes to render. |
||
Copy
|
|||
facets
|
type: ['*']|[]
default: ['*']
Optional
The facets to apply before dynamic widgets get mounted. Setting the value to |
||
Copy
|
|||
maxValuesPerFacet
|
type: number
default: 20
Optional
The default number of facet values to request. It’s recommended to have this value at least as high as the highest To avoid pinned items not showing in the result, make sure you choose a |
||
Copy
|
APIs
Hooks return APIs, such as state and functions. You can use them to build your UI and interact with React InstantSearch.
attributesToRender
|
type: string[]
The list of refinement values to display returned from the Algolia API. |
||
Copy
|
Example
1
2
3
4
5
6
7
8
9
import { RefinementList, useDynamicWidgets } from 'react-instantsearch';
function CustomDynamicWidgets(props) {
const { attributesToRender } = useDynamicWidgets(props);
return attributesToRender.map(attribute => (
<RefinementList key={attribute} attribute={attribute} />
));
}