> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# rangeSlider
> Lets users refine search results by a numeric range using a slider.
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
```ts Signature theme={"system"}
rangeSlider({
container: string | HTMLElement,
attribute: string,
// Optional parameters
min?: number,
max?: number,
precision?: number,
step?: number,
pips?: boolean,
tooltips?: boolean | object,
cssClasses?: object,
});
```
## Import
```js Package manager theme={"system"}
import { rangeSlider } from "instantsearch.js/es/widgets";
```
```js CDN theme={"system"}
const { rangeSlider } = instantsearch.widgets;
// or directly use instantsearch.widgets.rangeSlider()
```
Preview this widget and its behavior.
## About this widget
The `rangeSlider` widget provides a user-friendly way to filter the results,
based on a single numeric range.
### Requirements
The [`attribute`](#param-attribute) provided to the widget must be in attributes for faceting,
either on the [dashboard](/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting-with-dashboard) or using the [`attributesForFaceting`](/doc/api-reference/api-parameters/attributesForFaceting) parameter with the API.
The values of the attribute must be numbers, not strings.
## Examples
```js JavaScript icon=code theme={"system"}
rangeSlider({
container: "#range-slider",
attribute: "price",
});
```
## Options
The CSS Selector or `HTMLElement` to insert the widget into.
```js string theme={"system"}
rangeSlider({
// ...
container: "#range-slider",
});
```
```js HTMLElement theme={"system"}
rangeSlider({
// ...
container: document.querySelector("#range-slider"),
});
```
The name of the attribute in the record.
```js JavaScript icon=code theme={"system"}
rangeSlider({
// ...
attribute: "price",
});
```
The minimum value for the input.
When not provided, the minimum value is automatically computed by Algolia from the data in the index.
```js JavaScript icon=code theme={"system"}
rangeSlider({
// ...
min: 10,
});
```
The maximum value for the input.
When not provided, the maximum value is automatically computed by Algolia from the data in the index.
```js JavaScript icon=code theme={"system"}
rangeSlider({
// ...
max: 500,
});
```
The number of digits after the decimal point to use.
Use a negative value to round values to powers of 10.
For example, a precision of -2 would round a number to the nearest hundred,
while a precision of -3 would round it to the nearest thousand.
```js JavaScript icon=code theme={"system"}
// Round values to 2 digits after the decimal point
rangeSlider({
// ...
precision: 2,
});
// Round values to the nearest hundred
rangeSlider({
// ...
precision: -2,
});
```
The number of steps between each handle move.
```js JavaScript icon=code theme={"system"}
rangeSlider({
// ...
step: 5,
});
```
Whether to show slider pips.
```js JavaScript icon=code theme={"system"}
rangeSlider({
// ...
pips: false,
});
```
Whether to show tooltips.
The default tooltips show the raw value.
You can also provide an object with a `format` function.
```js boolean theme={"system"}
rangeSlider({
// ...
tooltips: false,
});
```
```js object theme={"system"}
rangeSlider({
// ...
tooltips: {
format(value) {
return `$${Math.round(value).toLocaleString()}`;
},
},
});
```
The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js#style-your-widgets):
* `root`. The root element of the widget.
* `handle`. The handle elements.
* `lowerHandle`. The handle for the minimum value.
* `upperHandle`. The handle for the maximum value.
* `tooltip`. The tooltip elements.
```js JavaScript icon=code theme={"system"}
rangeSlider({
// ...
cssClasses: {
root: "MyCustomrangeSlider",
handle: [
"MyCustomrangeSliderHandle",
"MyCustomrangeSliderHandle--subclass",
],
},
});
```
## HTML output
```html HTML icon=code-xml theme={"system"}
$750
$5,000
1
5,000
```
## Customize the UI with `connectRange`
If you want to create your own UI of the `rangeSlider` widget, you can use connectors.
This connector is also used to build the [`rangeInput`](/doc/api-reference/widgets/range-input/js) widget.
To use `connectRange`, you can import it with the declaration relevant to how you installed InstantSearch.js.
```js Package manager theme={"system"}
import { connectRange } from "instantsearch.js/es/connectors";
```
```js CDN theme={"system"}
const { connectRange } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectRange()
```
Then it's a 3-step process:
```js JavaScript icon=code theme={"system"}
// 1. Create a render function
const renderRangeSlider = (renderOptions, isFirstRender) => {
// Rendering logic
};
// 2. Create the custom widget
const customRangeSlider = connectRange(renderRangeSlider);
// 3. Instantiate
search.addWidgets([
customRangeSlider({
// instance params
}),
]);
```
### Create a render function
This rendering function is called before the first search (`init` lifecycle step)
and each time results come back from Algolia (`render` lifecycle step).
```js JavaScript icon=code theme={"system"}
const renderRangeSlider = (renderOptions, isFirstRender) => {
const { start, range, canRefine, refine, sendEvent, widgetParams } =
renderOptions;
if (isFirstRender) {
// Do some initial rendering and bind events
}
// Render the widget
};
```
#### Rendering options
The current value for the refinement,
with `start[0]` as the minimum value and `start[1]` as the maximum value.
```js JavaScript icon=code theme={"system"}
const renderRangeSlider = (renderOptions, isFirstRender) => {
const { start } = renderOptions;
document.querySelector("#range-slider").innerHTML = `
`;
};
```
The current available value for the range.
```js JavaScript icon=code theme={"system"}
const renderRangeSlider = (renderOptions, isFirstRender) => {
const { start, range } = renderOptions;
document.querySelector("#range-slider").innerHTML = `
`;
};
```
Indicates if search state can be refined.
```js JavaScript icon=code theme={"system"}
const renderRangeSlider = (renderOptions, isFirstRender) => {
const { canRefine } = renderOptions;
if (!canRefine) {
document.querySelector("#range-slider").innerHTML = "";
return;
}
};
```
Sets a range to filter the results on.
Both values are optional, and default to the higher and lower bounds.
You can use `undefined` to remove a previously set bound or to set an infinite bound.
```js JavaScript icon=code theme={"system"}
const renderRangeSlider = (renderOptions, isFirstRender) => {
const { start, range, refine } = renderOptions;
const container = document.querySelector("#range-slider");
if (isFirstRender) {
const input = document.createElement("input");
input.type = "range";
input.addEventListener("change", (event) => {
refine([parseFloat(event.currentTarget.value)]);
});
container.appendChild(input);
return;
}
const input = container.querySelector("input");
input.min = range.min;
input.max = range.max;
input.value = Number.isFinite(start[0]) ? start[0] : "0";
};
```
The function to send `click` events.
The `click` event is automatically sent when `refine` is called.
To learn more, see the [`insights`](/doc/api-reference/widgets/insights/js) middleware.
* `eventType: 'click'`
* `facetValue: string`
```js JavaScript icon=code theme={"system"}
// For example,
sendEvent("click", [10, 30]);
/*
A payload like the following will be sent to the `insights` middleware.
{
eventType: 'click',
insightsMethod: 'clickedFilters',
payload: {
eventName: 'Filter Applied',
filters: ['price>=10', 'price<=30'],
index: '',
},
widgetType: 'ais.range',
}
*/
```
All original widget options forwarded to the render function.
```js JavaScript icon=code theme={"system"}
const renderRangeSlider = (renderOptions, isFirstRender) => {
const { widgetParams } = renderOptions;
widgetParams.container.innerHTML = "...";
};
// ...
search.addWidgets([
customRangeSlider({
container: document.querySelector("#range-slider"),
}),
]);
```
### 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 customRangeSlider = connectRange(renderRangeSlider);
search.addWidgets([
customRangeSlider({
attribute: string, // Optional parametersmin:number,max:number,precision:number,
}),
]);
```
#### Instance options
The name of the attribute in the record.
```js JavaScript icon=code theme={"system"}
customRangeSlider({
attribute: "price",
});
```
The minimum value for the input.
When not provided, the minimum value is automatically computed by Algolia from the data in the index.
```js JavaScript icon=code theme={"system"}
customRangeSlider({
// ...
min: 10,
});
```
The maximum value for the input.
When not provided, the maximum value is automatically computed by Algolia from the data in the index.
```js JavaScript icon=code theme={"system"}
customRangeSlider({
// ...
max: 500,
});
```
The number of digits after the decimal point to use.
Use a negative value to round values to powers of 10.
For example, a precision of -2 would round a number to the nearest hundred,
while a precision of -3 would round it to the nearest thousand.
```js JavaScript icon=code theme={"system"}
// Round values to 2 digits after the decimal point
customRangeSlider({
// ...
precision: 2,
});
// Round values to the nearest hundred
customRangeSlider({
// ...
precision: -2,
});
```
### Full example
```html HTML theme={"system"}
```
```js JavaScript theme={"system"}
// Create the render function
const renderRangeSlider = (renderOptions, isFirstRender) => {
const { start, range, refine, widgetParams } = renderOptions;
if (isFirstRender) {
const input = document.createElement("input");
input.type = "range";
input.addEventListener("change", (event) => {
refine([parseFloat(event.currentTarget.value)]);
});
widgetParams.container.appendChild(input);
return;
}
const input = widgetParams.container.querySelector("input");
input.min = range.min;
input.max = range.max;
input.value = Number.isFinite(start[0]) ? start[0] : "0";
};
// Create the custom widget
const customRangeSlider = connectRange(renderRangeSlider);
// Instantiate the custom widget
search.addWidgets([
customRangeSlider({
container: document.querySelector("#range-slider"),
attribute: "price",
}),
]);
```