ais-dynamic-widgets

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

See this widget in action

Preview this widget and its behavior.

By default, <DynamicWidgets> requests all facets and up to 20 values per facet. These defaults help avoid another request after the matching widgets mount. Override the defaults with facets and maxValuesPerFacet. During server-side rendering, InstantSearch performs two render passes so that the UI includes the correct refinements.

You can also create your own UI with useDynamicWidgets.

Requirements

Declare each facet attribute in attributesForFaceting. Configure the facet order in the Algolia dashboard or with renderingContent.facetOrdering.

Example

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

React.ReactNode

The refinement widgets to render in the order specified by renderingContent.facetOrdering.Each child must define an attribute or attributes prop.

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

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

React.ReactNode

A component to render for each ordered facet attribute that doesn’t match a child.The component receives the unmatched facet attribute in its attribute prop.

<DynamicWidgets fallbackComponent={RefinementList} />;

export function RefinementList(props) {
  const { items, refine } = useRefinementList(props);

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

(items: string[], metadata: { results: SearchResults }) => string[]

Transforms the facet attributes before rendering.The second argument contains the search results, which you can use to derive a different attribute list.

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

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

import type { DynamicWidgetsProps } from "react-instantsearch";

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

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

['*']|[]

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.

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

<DynamicWidgets facets={[]} />;

number

default:20

The maximum number of values to request for each facet.Set this value to at least the highest limit or showMoreLimit used by a dynamic widget. This helps avoid an additional request after the widget mounts.Set maxValuesPerFacet to at least the largest number of pinned values configured for any facet. Otherwise, some pinned values might not appear.

JavaScript

<DynamicWidgets maxValuesPerFacet={500} />;

Hook

Use the useDynamicWidgets Hook to build a custom dynamic widgets UI. The Hook must run inside <InstantSearch>. React InstantSearch lets you create your own UI for the <DynamicWidgets> widget with useDynamicWidgets. Hooks provide APIs to access the widget state and interact with InstantSearch.

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.

function

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

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

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

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

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

['*']|[]

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.

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

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

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

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

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.

string[]

The ordered facet attributes to render, derived from []renderingContent.facetOrdering.facets.order](/doc/api-reference/api-parameters/renderingContent#param-facets-order).

JavaScript

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

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

Example

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

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

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

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

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

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

​Import

See this widget in action

​About this widget

​Requirements

​Example

​Props

​Hook

​Usage

​Parameters

​APIs

​Example

Import

About this widget

Requirements

Example

Props

Hook

Usage

Parameters

APIs

Example