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

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>
  );
}

1
2
3
4
5
6
<DynamicWidgets>
  <HierarchicalMenu
    attributes={['hierarchical.lvl0', 'hierarchical.lvl1']}
  />
  <RefinementList attribute="brand" />
</DynamicWidgets>

1
2
3
4
5
6
7
8
9
10
<DynamicWidgets>
  <Panel header="Categories">
    <HierarchicalMenu
      attributes={['hierarchical.lvl0', 'hierarchical.lvl1']}
    />
  </Panel>
  <Panel header="Brands">
    <RefinementList attribute="brand" />
  </Panel>
</DynamicWidgets>

1
<DynamicWidgets fallbackComponent={RefinementList} />

1
2
3
4
5
export function RefinementList(props) {
  const { items, refine } = useRefinementList(props);

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

1
2
3
4
5
6
7
8
9
const transformItems = (items, { results }) => {
  return results.userData.customOrdering;
};

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

1
2
3
4
5
6
7
8
9
10
11
import type { DynamicWidgetsProps } from 'react-instantsearch';

const transformItems: DynamicWidgetsProps['transformItems'] = (items, { results }) => {
  return results.userData.customOrdering;
};

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

1
<DynamicWidgets facets={['*']} />

1
<DynamicWidgets facets={[]} />

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.

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.

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 */}</>;
}

1
2
3
4
5
6
7
8
9
10
11
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 */}</>;
}

1
2
3
4
5
6
7
function DynamicWidgets() {
  const dynamicWidgetsApi = useDynamicWidgets({
    facets: ['*']
  });

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

1
2
3
4
5
6
7
function DynamicWidgets() {
  const dynamicWidgetsApi = useDynamicWidgets({
    facets: []
  });

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

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.

1
2
3
4
5
6
7
function DynamicWidgets(props) {
  const { attributesToRender } = useDynamicWidgets(props);

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

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} />
  ));
}

1
2
3
4
5
6
7
8
9
10
11
12
13
import {
  RefinementList,
  useDynamicWidgets,
  UseDynamicWidgetsProps,
} from 'react-instantsearch';

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

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