UI libraries / React InstantSearch / Widgets

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

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

import { DynamicWidgets } from 'react-instantsearch';
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 frontend are correct.

Requirements

You must set the attributes for faceting and configure the facet order, either using the dashboard) or 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

Copy 
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

Parameter Description
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 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';

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.

Parameter Description
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.

Parameter Description
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';

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

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