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

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

<CodeGroup>
  ```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()
  ```
</CodeGroup>

<Card title="See this widget in action" icon="monitor-play" href="https://instantsearchjs.netlify.app/stories/js/?path=/story/refinements-rangeslider--default" horizontal>
  Preview this widget and its behavior.
</Card>

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

<ParamField body="container" type="string | HTMLElement" required>
  The CSS Selector or `HTMLElement` to insert the widget into.

  <CodeGroup>
    ```js string theme={"system"}
    rangeSlider({
      // ...
      container: "#range-slider",
    });
    ```

    ```js HTMLElement theme={"system"}
    rangeSlider({
      // ...
      container: document.querySelector("#range-slider"),
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="attribute" type="string" required>
  The name of the attribute in the record.

  ```js JavaScript icon=code theme={"system"}
  rangeSlider({
    // ...
    attribute: "price",
  });
  ```
</ParamField>

<ParamField body="min" type="number">
  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,
  });
  ```
</ParamField>

<ParamField body="max" type="number">
  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,
  });
  ```
</ParamField>

<ParamField body="precision" type="number" default={0}>
  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,
  });
  ```
</ParamField>

<ParamField body="step" type="number">
  The number of steps between each handle move.

  ```js JavaScript icon=code theme={"system"}
  rangeSlider({
    // ...
    step: 5,
  });
  ```
</ParamField>

<ParamField body="pips" type="boolean">
  Whether to show slider pips.

  ```js JavaScript icon=code theme={"system"}
  rangeSlider({
    // ...
    pips: false,
  });
  ```
</ParamField>

<ParamField body="tooltips" type="boolean | object">
  Whether to show tooltips.
  The default tooltips show the raw value.
  You can also provide an object with a `format` function.

  <CodeGroup>
    ```js boolean theme={"system"}
    rangeSlider({
      // ...
      tooltips: false,
    });
    ```

    ```js object theme={"system"}
    rangeSlider({
      // ...
      tooltips: {
        format(value) {
          return `$${Math.round(value).toLocaleString()}`;
        },
      },
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="cssClasses" type="object" default="{}">
  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",
      ],
    },
  });
  ```
</ParamField>

## HTML output

```html HTML icon=code-xml theme={"system"}
<div class="ais-RangeSlider">
  <div class="rheostat rheostat-horizontal" style="position: relative;">
    <div class="rheostat-background"></div>
    <div
      class="rheostat-handle rehostat-handle--lower"
      aria-valuemax="5000"
      aria-valuemin="1"
      aria-valuenow="750"
      aria-disabled="false"
      data-handle-key="0"
      role="slider"
      tabindex="0"
      style="left: 15%; position: absolute;"
    >
      <div class="rheostat-tooltip">$750</div>
    </div>
    <div
      class="rheostat-handle rheostat-handle--upper"
      aria-valuemax="5000"
      aria-valuemin="750"
      aria-valuenow="5000"
      aria-disabled="false"
      data-handle-key="1"
      role="slider"
      tabindex="0"
      style="left: 100%; position: absolute;"
    >
      <div class="rheostat-tooltip">$5,000</div>
    </div>
    <div class="rheostat-progress" style="left: 15%; width: 85%;"></div>
    <div
      class="rheostat-marker rheostat-marker--large"
      style="left: 0%; position: absolute; margin-left: 0px;"
    >
      <div class="rheostat-value">1</div>
    </div>
    <div
      class="rheostat-marker"
      style="left: 2.94118%; position: absolute; margin-left: 0px;"
    ></div>
    <!-- ... -->
    <div
      class="rheostat-marker"
      style="left: 97.0588%; position: absolute; margin-left: 0px;"
    ></div>
    <div
      class="rheostat-marker rheostat-marker--large"
      style="left: 100%; position: absolute; margin-left: -1px;"
    >
      <div class="rheostat-value">5,000</div>
    </div>
  </div>
</div>
```

## Customize the UI with `connectRange`

If you want to create your own UI of the `rangeSlider` widget, you can use connectors.

<Info>
  This connector is also used to build the [`rangeInput`](/doc/api-reference/widgets/range-input/js) widget.
</Info>

To use `connectRange`, you can import it with the declaration relevant to how you installed InstantSearch.js.

<CodeGroup>
  ```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()
  ```
</CodeGroup>

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

<ParamField body="start" type="number[]">
  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 = `
      <input type="range" value="${Number.isFinite(start[0]) ? start[0] : "0"}" />
    `;
  };
  ```
</ParamField>

<ParamField body="range" type="object">
  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 = `
      <input
        type="range"
        min="${range.min}"
        max="${range.max}"
        value="${Number.isFinite(start[0]) ? start[0] : "0"}"
      />
    `;
  };
  ```
</ParamField>

<ParamField body="canRefine" type="boolean" required>
  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;
    }
  };
  ```
</ParamField>

<ParamField body="refine" type="function">
  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";
  };
  ```
</ParamField>

<ParamField body="sendEvent" type="(eventType, facetValue) => void">
  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',
    }
  */
  ```
</ParamField>

<ParamField body="widgetParams" type="object">
  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"),
    }),
  ]);
  ```
</ParamField>

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

<ParamField body="attribute" type="string" required>
  The name of the attribute in the record.

  ```js JavaScript icon=code theme={"system"}
  customRangeSlider({
    attribute: "price",
  });
  ```
</ParamField>

<ParamField body="min" type="number">
  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,
  });
  ```
</ParamField>

<ParamField body="max" type="number">
  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,
  });
  ```
</ParamField>

<ParamField body="precision" type="number" default={0}>
  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,
  });
  ```
</ParamField>

### Full example

<CodeGroup>
  ```html HTML theme={"system"}
  <div id="range-slider"></div>
  ```

  ```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",
    }),
  ]);
  ```
</CodeGroup>