InstantSearch / React / V6 / API reference

DynamicWidgets | React InstantSearch V6 (Deprecated)

Deprecated content
This documentation is for a deprecated version of React InstantSearch. Some features and settings may be missing or their usage may have changed. Refer to the documentation for the latest version of React InstantSearch for up-to-date information.

Signature

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

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.

Examples

[object Object]

Props

children

Optional
Type: Element[]

The children of this component will be displayed dynamically based on the result of facetOrdering. This means that any child needs to have either the “attribute” or “attributes” prop.

1
2
3
<DynamicWidgets>
  <RefinementList attribute="brand" />
</DynamicWidgets>
1
2
3
4
5
6
7
8
9
<DynamicWidgets>
  <HierarchicalMenu
    attributes={[
      'hierarchicalCategories.lvl0',
      'hierarchicalCategories.lvl1',
      'hierarchicalCategories.lvl2',
    ]}
  />
</DynamicWidgets>
1
2
3
4
5
<DynamicWidgets>
  <Panel header="Brands">
    <RefinementList attribute="brand" />
  </Panel>
</DynamicWidgets>
1
2
3
4
5
6
7
8
9
const CustomRefinementList = connectRefinementList(
  () => {
    // implement custom widget
  }
);

<DynamicWidgets>
  <CustomRefinementList attribute="brand"/>
</DynamicWidgets>

fallbackComponent

Optional
Type: Widget

The fallbackComponent prop is used if no widget from children matches. The component gets called with an attribute prop.

1
<DynamicWidgets fallbackComponent={RefinementList} />
1
2
3
4
5
function CustomWidget({ attribute }) {
  return <RefinementList attribute={attribute} showMore searchable/>
}

<DynamicWidgets fallbackComponent={CustomWidget} />

transformItems

Optional
Type: function

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

1
2
3
4
5
<DynamicWidgets
  transformItems={(items, { results }) => {
    return items;
  }},
/>

facets

Optional
Type: ['*']|[]

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.

1
2
3
4
<DynamicWidgets
  // ...
  facets={['*']}
/>
1
2
3
4
<DynamicWidgets
  // ...
  facets={[]}
/>

maxValuesPerFacet

Optional
Type: number

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

1
2
3
4
<DynamicWidgets
  // ...
  maxValuesPerFacet={500}
/>
Did you find this page helpful?