dynamicWidgets

Renders matching refinement widgets in the facet order returned by Algolia.

Signature

dynamicWidgets({
  container: string | HTMLElement,
  widgets: function[],
  // Optional parameters
  transformItems?: function,
  fallbackWidget?: function,
  facets?: ['*']|[],
  maxValuesPerFacet?: number,
});

Import

Package manager

import { dynamicWidgets } from "instantsearch.js/es/widgets";

See this widget in action

Preview this widget and its behavior.

About this widget

Requirements

Declare each facet attribute in attributesForFaceting.

Configure the facet order in the Algolia dashboard or with renderingContent.facetOrdering.

By default, dynamicWidgets requests all facets with facets: ["*"] and requests up to 20 values per facet. These defaults help avoid a second request after the matching widgets mount.

Override these defaults with facets and maxValuesPerFacet.

dynamicWidgets requires InstantSearch.js 4.72.0 or later.

Examples

Default

dynamicWidgets({
  container: "#dynamic-widgets",
  widgets: [
    (container) => refinementList({ container, attribute: "brand" }),
    (container) =>
      hierarchicalMenu({
        container,
        attributes: [
          "hierarchicalCategories.lvl0",
          "hierarchicalCategories.lvl1",
        ],
      }),
  ],
  fallbackWidget: ({ container, attribute }) =>
    panel({ templates: { header: attribute } })(menu)({ container, attribute }),
});

Options

container · string | HTMLElement · required

A CSS selector or HTMLElement that contains the widget.

String

dynamicWidgets({
  // ...
  container: "#dynamic-widgets",
});

widgets · Array<(container: HTMLElement) => Widget> · required

An array of functions that create refinement widgets.

Each function receives a container and returns a widget. The returned widget must define an attribute or attributes option so that dynamicWidgets can match and order it.

The function can also return a custom widget created with a connector.

Widget

dynamicWidgets({
  // ...
  widgets: [(container) => refinementList({ container, attribute: "brand" })],
});

fallbackWidget · (args: { attribute: string, container: HTMLElement }) => Widget

A function that’s called for every attribute you want to display. It receive a container and attribute and is expected to return a widget. The function can also return custom widgets created with connectors.

Widget

dynamicWidgets({
  // ...
  fallbackWidget: ({ container, attribute }) =>
    refinementList({ container, attribute }),
});

transformItems · function

Transforms the facet attributes before rendering.

The second argument includes the search results, which you can use to derive a different attribute list.

JavaScript

dynamicWidgets({
  // ...
  transformItems(items, { results }) {
    return items;
  },
});

facets · ['*']|[] · default: "['*']"

The facets to apply before dynamic widgets are mounted. Setting the value to ['*'] requests all facets and avoids an additional network request.

Default

dynamicWidgets({
  // ...
  facets: ["*"],
});

maxValuesPerFacet · 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,
});

Customize the UI with connectDynamicWidgets

Use connectDynamicWidgets to build a custom UI for dynamicWidgets.

Import the connector using the method that matches your InstantSearch.js installation.

Package manager

import { connectDynamicWidgets } from "instantsearch.js/es/connectors";

Create a render function, pass it to connectDynamicWidgets, and add the resulting widget to the search:

JavaScript

// 1. Create a render function
const renderDynamicWidgets = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customDynamicWidgets = connectDynamicWidgets(renderDynamicWidgets);

// 3. Instantiate
search.addWidgets([
  customDynamicWidgets({
    // instance params
  }),
]);

Create a render function

InstantSearch.js calls the render function before the first search during the init lifecycle and each time results come back from Algolia (render lifecycle step).

JavaScript

const renderDynamicWidgets = (renderOptions, isFirstRender) => {
  const { attributesToRender, widgetParams } = renderOptions;

  if (isFirstRender) {
    // Set up the initial DOM and event listeners.
  }

  // Render the widget
};

Rendering options

attributesToRender · string[]

The ordered facet attributes to render, derived from renderingContent.facetOrdering.facets.order.

JavaScript

const renderDynamicWidgets = (renderOptions, isFirstRender) => {
  const { attributesToRender } = renderOptions;

  document.querySelector("#dynamic-widgets").innerHTML = `
    <ul>
      ${attributesToRender
        .map(
          (attribute) => `
            <li>
              ${attribute}
            </li>`,
        )
        .join("")}
    </ul>
  `;
};

widgetParams · object

All original widget options forwarded to the render function.

JavaScript

const renderDynamicWidgets = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

  widgetParams.container.innerHTML = "...";
};

// ...

search.addWidgets([
  customDynamicWidgets({
    // ...
    container: document.querySelector("#dynamic-widgets"),
  }),
]);

Create and instantiate the custom widget

First, create your custom widgets using a rendering function. Then, instantiate them with parameters.

There are two kinds of parameters you can pass:

• Instance parameters. Predefined options that configure Algolia’s behavior.
• Custom parameters. Parameters you define to make the widget reusable and adaptable.

Inside the renderFunction, both instance and custom parameters are accessible through connector.widgetParams.

JavaScript

const customDynamicWidgets = connectDynamicWidgets(
  renderDynamicWidgets
);

search.addWidgets([
  customDynamicWidgets({
    widgets: object[],
    // Optional parameters
    transformItems?: function,
    facets?: string[],
    maxValuesPerFacet?: number,
  })
]);

Instance options

widgets · object[] · required

The widgets to add to the parent index.

Update their DOM positions in the render function to match the order in attributesToRender.

JavaScript

customDynamicWidgets({
  widgets: [
    refinementList({
      // ...
    }),
    customWidget({
      // ...
    }),
  ],
});

transformItems · function

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

JavaScript

customDynamicWidgets({
  // ...
  transformItems(items, { results }) {
    return items;
  },
});

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

customDynamicWidgets({
  // ...
  facets: ["*"],
});

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

JavaScript

customDynamicWidgets({
  // ...
  maxValuesPerFacet: 500,
});

Full example

HTML

<div id="dynamic-widgets"></div>

JavaScript

// Create a mapping between widgets and their attribute
const { rangeSlider, refinementList } = instantsearch.widgets;
const widgets = {
  brand: {
    widget: (container) => refinementList({ attribute: "brand", container }),
    container: document.createElement("div"),
  },
  price: {
    widget: (container) => rangeSlider({ attribute: "price", container }),
    container: document.createElement("div"),
  },
};

// Create a render function
const renderDynamicWidgets = (renderOptions, isFirstRender) => {
  const { attributesToRender, widgetParams } = renderOptions;

  if (isFirstRender) {
    const ul = document.createElement("ul");
    widgetParams.container.appendChild(ul);
  }

  const ul = widgetParams.container.querySelector("ul");
  ul.innerHTML = "";

  attributesToRender.forEach((attribute) => {
    if (!widgets[attribute]) {
      return;
    }

    const container = widgets[attribute].container;
    ul.appendChild(container);
  });
};

// Create the custom widget
const customDynamicWidgets = connectDynamicWidgets(renderDynamicWidgets);

// Instantiate
search.addWidgets([
  customDynamicWidgets({
    container: document.querySelector("#dynamic-widgets"),
    widgets: Object.values(widgets).map(({ widget, container }) =>
      widget(container),
    ),
  }),
]);