> ## Documentation Index
> Fetch the complete documentation index at: https://www.algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# dynamicWidgets
> Renders matching refinement widgets in the facet order returned by Algolia.
export const DynamicFacets = ({current}) =>
This widget displays matching refinement widgets in the order provided by{" "}
renderingContent.facetOrdering
{" "}
in the search response.
Configure the order with{" "}
facet display
, override it with{" "}
Algolia Rules
, or generate it automatically with{" "}
Dynamic Facets
. Dynamic Facets orders facets and facet values based on recent search
data.
;
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
FlavorSwitcher requires at least one option.
;
}
const selected = options.find(option => option.value === current) ?? options[0];
return ;
};
```ts Signature theme={"system"}
dynamicWidgets({
container: string | HTMLElement,
widgets: function[],
// Optional parameters
transformItems?: function,
fallbackWidget?: function,
facets?: ['*']|[],
maxValuesPerFacet?: number,
});
```
## Import
```js Package manager theme={"system"}
import { dynamicWidgets } from "instantsearch.js/es/widgets";
```
```js CDN theme={"system"}
const { dynamicWidgets } = instantsearch.widgets;
// Use instantsearch.widgets.dynamicWidgets()
```
Preview this widget and its behavior.
## About this widget
### Requirements
Declare each facet attribute in [`attributesForFaceting`](/doc/api-reference/api-parameters/attributesForFaceting).
Configure the facet order in the [Algolia dashboard](/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting-with-dashboard) or
with [`renderingContent.facetOrdering`](/doc/api-reference/api-parameters/renderingContent#param-facet-ordering).
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`](#param-facets) and [`maxValuesPerFacet`](#param-max-values-per-facet).
`dynamicWidgets` requires InstantSearch.js 4.72.0 or later.
## Examples
```js Default theme={"system"}
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 }),
});
```
```js Request customization theme={"system"}
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 }),
// Send a second request after the widgets mount.
facets: [],
// Set this to at least the number of pinned values.
maxValuesPerFacet: 100,
});
```
## Options
A CSS selector or `HTMLElement` that contains the widget.
```js String theme={"system"}
dynamicWidgets({
// ...
container: "#dynamic-widgets",
});
```
```js HTMLElement theme={"system"}
dynamicWidgets({
// ...
container: document.querySelector("#dynamic-widgets"),
});
```
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.
```js Widget theme={"system"}
dynamicWidgets({
// ...
widgets: [(container) => refinementList({ container, attribute: "brand" })],
});
```
```js Hierarchical icon=code theme={"system"}
dynamicWidgets({
// ...
widgets: [
(container) =>
hierarchicalMenu({
container,
attributes: [
"hierarchicalCategories.lvl0",
"hierarchicalCategories.lvl1",
],
}),
],
});
```
```js Panel theme={"system"}
dynamicWidgets({
// ...
widgets: [
(container) =>
panel({
templates: { header: "Brand" },
})(refinementList)({
container,
attribute: "brand",
}),
],
});
```
```js Custom widget theme={"system"}
const customRefinementList = connectRefinementList(() => {
// Implement custom widget
});
dynamicWidgets({
// ...
widgets: [
(container) =>
customRefinementList({
container,
attribute: "brand",
}),
],
});
```
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.
```js Widget theme={"system"}
dynamicWidgets({
// ...
fallbackWidget: ({ container, attribute }) =>
refinementList({ container, attribute }),
});
```
```js Panel theme={"system"}
dynamicWidgets({
// ...
fallbackWidget: ({ container, attribute }) =>
panel({
templates: { header: attribute },
})(refinementList)({ container, attribute }),
});
```
```js Custom widget theme={"system"}
const customRefinementList = connectRefinementList(() => {
// implement custom widget
});
dynamicWidgets({
// ...
fallbackWidget: ({ container, attribute }) =>
customRefinementList({ container, attribute }),
});
```
Transforms the facet attributes before rendering.
The second argument includes the search results, which you can use to derive a different attribute list.
```js JavaScript icon=code theme={"system"}
dynamicWidgets({
// ...
transformItems(items, { results }) {
return items;
},
});
```
The facets to apply before dynamic widgets are mounted.
Setting the value to `['*']` requests all facets and avoids an additional network request.
```js Default theme={"system"}
dynamicWidgets({
// ...
facets: ["*"],
});
```
```js No facets theme={"system"}
dynamicWidgets({
// ...
facets: [],
});
```
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.
```js JavaScript icon=code theme={"system"}
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.
```js Package manager theme={"system"}
import { connectDynamicWidgets } from "instantsearch.js/es/connectors";
```
```js CDN theme={"system"}
const { connectDynamicWidgets } = instantsearch.connectors;
// Use instantsearch.connectors.connectDynamicWidgets()
```
Create a render function, pass it to `connectDynamicWidgets`,
and add the resulting widget to the search:
```js JavaScript icon=code theme={"system"}
// 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).
```js JavaScript icon=code theme={"system"}
const renderDynamicWidgets = (renderOptions, isFirstRender) => {
const { attributesToRender, widgetParams } = renderOptions;
if (isFirstRender) {
// Set up the initial DOM and event listeners.
}
// Render the widget
};
```
#### Rendering options
The ordered facet attributes to render,
derived from [`renderingContent.facetOrdering.facets.order`](/doc/api-reference/api-parameters/renderingContent#param-facets-order).
```js JavaScript icon=code theme={"system"}
const renderDynamicWidgets = (renderOptions, isFirstRender) => {
const { attributesToRender } = renderOptions;
document.querySelector("#dynamic-widgets").innerHTML = `
${attributesToRender
.map(
(attribute) => `
-
${attribute}
`,
)
.join("")}
`;
};
```
All original widget options forwarded to the render function.
```js JavaScript icon=code theme={"system"}
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.
You can pass two kinds of parameters:
* **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`.
```js JavaScript icon=code theme={"system"}
const customDynamicWidgets = connectDynamicWidgets(
renderDynamicWidgets
);
search.addWidgets([
customDynamicWidgets({
widgets: object[],
// Optional parameters
transformItems?: function,
facets?: string[],
maxValuesPerFacet?: number,
})
]);
```
#### Instance options
The widgets to add to the parent index.
Update their DOM positions in the render function to match the order in `attributesToRender`.
```js JavaScript icon=code theme={"system"}
customDynamicWidgets({
widgets: [
refinementList({
// ...
}),
customWidget({
// ...
}),
],
});
```
A function to transform the attributes to render,
or using a different source to determine the attributes to render.
```js JavaScript icon=code theme={"system"}
customDynamicWidgets({
// ...
transformItems(items, { results }) {
return items;
},
});
```
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.
```js Default theme={"system"}
customDynamicWidgets({
// ...
facets: ["*"],
});
```
```js No facets theme={"system"}
customDynamicWidgets({
// ...
facets: [],
});
```
The default number of facet values to request.
Set this value at least as high as the highest `limit` and `showMoreLimit` of dynamic widgets,
to 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.
```js JavaScript icon=code theme={"system"}
customDynamicWidgets({
// ...
maxValuesPerFacet: 500,
});
```
### Full example
```html HTML icon=code-xml theme={"system"}
```
```js JavaScript icon=code expandable theme={"system"}
// 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),
),
}),
]);
```