> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# rangeInput
> Lets users enter a numeric range for refining search results.
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
```ts Signature theme={"system"}
rangeInput({
container: string | HTMLElement,
attribute: string,
// Optional parameters
min?: number,
max?: number,
precision?: number,
templates?: object,
cssClasses?: object,
});
```
## Import
```js Package manager theme={"system"}
import { rangeInput } from "instantsearch.js/es/widgets";
```
```js CDN theme={"system"}
const { rangeInput } = instantsearch.widgets;
// or directly use instantsearch.widgets.rangeInput()
```
Preview this widget and its behavior.
## About this widget
The `rangeInput` widget allows a user to select a numeric range using a minimum and maximum input.
### 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"}
rangeInput({
container: "#range-input",
attribute: "price",
});
```
## Options
The CSS Selector or `HTMLElement` to insert the widget into.
```js string theme={"system"}
rangeInput({
// ...
container: "#range-input",
});
```
```js HTMLElement theme={"system"}
rangeInput({
// ...
container: document.querySelector("#range-input"),
});
```
The name of the attribute in the record.
```js JavaScript icon=code theme={"system"}
rangeInput({
// ...
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"}
rangeInput({
// ...
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"}
rangeInput({
// ...
max: 500,
});
```
The number of digits after the decimal point to use.
```js JavaScript icon=code theme={"system"}
rangeInput({
// ...
precision: 2,
});
```
The [templates](#templates) to use for the widget.
```js JavaScript icon=code theme={"system"}
rangeInput({
// ...
templates: {
// ...
},
});
```
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.
* `form`. The form element.
* `label`. The label elements.
* `input`. The input elements.
* `inputMin`. The minimum input element.
* `inputMax`. The maximum input element.
* `separator`. The separator element.
* `submit`. The submit button.
```js JavaScript icon=code theme={"system"}
rangeInput({
// ...
cssClasses: {
root: "MyCustomRangeInput",
form: ["MyCustomRangeInputForm", "MyCustomRangeInputForm--subclass"],
},
});
```
## Templates
You can customize parts of a widget’s UI using the Templates API.
Each template includes an `html` function,
which you can use as a [tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates).
This function safely renders templates as HTML strings and works directly in the browser—no build step required.
For details, see [Templating your UI](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js/#templating-your-ui).
The `html` function is available in InstantSearch.js version 4.46.0 or later.
The template for the separator, between the minimum and maximum inputs.
```js function theme={"system"}
rangeInput({
// ...
templates: {
separatorText(_, { html }) {
return html`to`;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
rangeInput({
// ...
templates: {
separatorText: "to",
},
});
```
The template for the submit button.
```js function theme={"system"}
rangeInput({
// ...
templates: {
submitText(_, { html }) {
return html`Go`;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
rangeInput({
// ...
templates: {
submitText: "Go",
},
});
```
## HTML output
```html HTML icon=code-xml theme={"system"}
```
## Customize the UI with `connectRange`
If you want to create your own UI of the `rangeInput` widget, you can use connectors.
This connector is also used to build the [`rangeSlider`](/doc/api-reference/widgets/range-slider/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 renderRangeInput = (renderOptions, isFirstRender) => {
// Rendering logic
};
// 2. Create the custom widget
const customRangeInput = connectRange(renderRangeInput);
// 3. Instantiate
search.addWidgets([
customRangeInput({
// 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 renderRangeInput = (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 renderRangeInput = (renderOptions, isFirstRender) => {
const { start } = renderOptions;
const [min, max] = start;
document.querySelector("#range-input").innerHTML = `
`;
};
```
The current available value for the range.
```js JavaScript icon=code theme={"system"}
const renderRangeInput = (renderOptions, isFirstRender) => {
const { range } = renderOptions;
document.querySelector("#range-input").innerHTML = `
`;
};
```
Indicates if search state can be refined.
```js JavaScript icon=code theme={"system"}
const renderRangeInput = (renderOptions, isFirstRender) => {
const { range, canRefine } = renderOptions;
if (!canRefine) {
document.querySelector("#range-input").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 renderRangeInput = (renderOptions, isFirstRender) => {
const { start, refine } = renderOptions;
const [min, max] = start;
const container = document.querySelector("#range-input");
if (isFirstRender) {
const form = document.createElement("form");
form.addEventListener("submit", (event) => {
event.preventDefault();
const [minInput, maxInput] = event.target.elements;
const rawMinInputValue = parseFloat(minInput.value);
const rawMaxInputValue = parseFloat(maxInput.value);
refine([
Number.isFinite(rawMinInputValue) ? rawMinInputValue : undefined,
Number.isFinite(rawMaxInputValue) ? rawMaxInputValue : undefined,
]);
});
container.appendChild(form);
}
container.querySelector("form").innerHTML = `
to
`;
};
```
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 renderRangeInput = (renderOptions, isFirstRender) => {
const { widgetParams } = renderOptions;
widgetParams.container.innerHTML = "...";
};
// ...
search.addWidgets([
customRangeInput({
container: document.querySelector("#range-input"),
}),
]);
```
### 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 customRangeInput = connectRange(renderRangeInput);
search.addWidgets([
customRangeInput({
attribute: string,
// Optional parameters
min: number,
max: number,
precision: number,
}),
]);
```
#### Instance options
The name of the attribute in the record.
```js JavaScript icon=code theme={"system"}
customRangeInput({
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"}
customRangeInput({
// ...
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"}
customRangeInput({
// ...
max: 500,
});
```
The number of digits after the decimal point to use.
```js JavaScript icon=code theme={"system"}
customRangeInput({
// ...
precision: 2,
});
```
### Full example
```html HTML theme={"system"}
```
```js JavaScript theme={"system"}
// Create the render function
const renderRangeInput = (renderOptions, isFirstRender) => {
const { start, range, refine, widgetParams } = renderOptions;
const [min, max] = start;
if (isFirstRender) {
const form = document.createElement("form");
form.addEventListener("submit", (event) => {
event.preventDefault();
const rawMinInputValue = parseFloat(event.target.elements.min.value);
const rawMaxInputValue = parseFloat(event.target.elements.max.value);
refine([
Number.isFinite(rawMinInputValue) ? rawMinInputValue : undefined,
Number.isFinite(rawMaxInputValue) ? rawMaxInputValue : undefined,
]);
});
widgetParams.container.appendChild(form);
return;
}
widgetParams.container.querySelector("form").innerHTML = `
to
`;
};
// Create the custom widget
const customRangeInput = connectRange(renderRangeInput);
// Instantiate the custom widget
search.addWidgets([
customRangeInput({
container: document.querySelector("#range-input"),
attribute: "price",
}),
]);
```