> ## Documentation Index
> Fetch the complete documentation index at: https://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.
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`.
```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.
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.
```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),
),
}),
]);
```