API Reference / React InstantSearch Hooks / <DynamicWidgets>

<DynamicWidgets>

Signature 
<DynamicWidgets
  // Optional parameters
  transformItems={function}
  fallbackComponent={ReactNode}
  facets={['*'] | []}
  maxValuesPerFacet={number}
>
  {children}
</DynamicWidgets>
Import
Copy 
1

import { DynamicWidgets } from 'react-instantsearch-hooks-web';
See code examples
See live example

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 front-end are correct.

Requirements

You must set the attributes for faceting attributesForFaceting and configure the facet order, either using the dashboard or using attributesForFaceting and renderingContent respectively with the API.

You can also create your own UI with useDynamicWidgets().

You must use at least React InstantSearch Hooks version 6.16.0 to use ****.

Examples

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

import {
  InstantSearch,
  DynamicWidgets,
} from 'react-instantsearch-hooks-web';

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 facetOrdering.

Any child needs to have either an attribute or attributes prop.
Copy 
1
2
3
4
5
6

<DynamicWidgets>
  <HierarchicalMenu
    attributes={['hierarchical.lvl0', 'hierarchical.lvl1']}
  />
  <RefinementList attribute="brand" />
</DynamicWidgets>
fallbackComponent
type: React.ReactNode
Optional

Component used if none of the children matches the attribute or attributes[0] prop.
Copy 
1

<DynamicWidgets fallbackComponent={RefinementList} />
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 
1
2
3
4
5
6
7
8
9

const transformItems = (items, { results }) => {
  return results.userData.customOrdering;
};

function Search() {
  return (
    <DynamicWidgets transformItems={transformItems} />
  );
}
facets
type: ['*']|[]
default: ['*']
Optional

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.
Copy 
1

<DynamicWidgets facets={['*']} />
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 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.
Copy 
1

<DynamicWidgets maxValuesPerFacet={500} />

Hook

React InstantSearch Hooks 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.

See code examples

Usage

First, create your React component:

import { useDynamicWidgets } from 'react-instantsearch-hooks-web';

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 
1
2
3
4
5
6
7
8
9

const transformItems = (items, { results }) => {
  return results.userData.customOrdering;
};

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

  return <>{/* Your JSX */}</>;
}
facets
type: ['*']|[]
default: ['*']
Optional

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.
Copy 
1
2
3
4
5
6
7

function DynamicWidgets() {
  const dynamicWidgetsApi = useDynamicWidgets({
    facets: ['*']
  });

  return <>{/* Your JSX */}</>;
}
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 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.
Copy 
1
2
3
4
5
6
7

  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.

attributesToRender
type: string[]

The list of refinement values to display returned from the Algolia API.
Copy 
1
2
3
4
5
6
7

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

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

Example

Copy 
1
2
3
4
5
6
7
8
9

import { RefinementList, useDynamicWidgets } from 'react-instantsearch-hooks-web';

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

  return attributesToRender.map(attribute => (
    <RefinementList key={attribute} attribute={attribute} />
  ));
}
Did you find this page helpful?
React InstantSearch Hooks v6