DynamicWidgets

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

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.

Signature

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

Import

JavaScript

import { DynamicWidgets } from "react-instantsearch";

View demo

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.

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

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.

Examples

JavaScript

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

Direct children

<DynamicWidgets>
  <HierarchicalMenu attributes={["hierarchical.lvl0", "hierarchical.lvl1"]} />
  <RefinementList attribute="brand" />
</DynamicWidgets>;

fallbackComponent · React.ReactNode

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

App.js

<DynamicWidgets fallbackComponent={RefinementList} />;

transformItems · (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.

JavaScript

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

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

facets · ['*']|[] · 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.

All facets

<DynamicWidgets facets={["*"]} />;

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

JavaScript

<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. It must be used inside the <InstantSearch> component.

Usage

First, create your React component:

JavaScript

import { useDynamicWidgets } from "react-instantsearch";

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

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

Then, render the widget:

JavaScript

<CustomDynamicWidgets {...props} />;

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() for memoization. Arrays and objects are automatically memoized.

transformItems · function

A function to transform the attributes to render, or using a different source to determine the attributes to render.

JavaScript

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

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

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

facets · ['*']|[] · 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.

Default

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

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

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

JavaScript

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 · string[]

The list of refinement values to display returned from the Algolia API.

JavaScript

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

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

Example

JavaScript

import { RefinementList, useDynamicWidgets } from "react-instantsearch";

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

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