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

```ts Signature theme={"system"}
rangeInput({
  container: string | HTMLElement,
  attribute: string,
  // Optional parameters
  min?: number,
  max?: number,
  precision?: number,
  templates?: object,
  cssClasses?: object,
});
```

## Import

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

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

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

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

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

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

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

  ```js JavaScript icon=code theme={"system"}
  rangeInput({
    // ...
    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"}
  rangeInput({
    // ...
    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"}
  rangeInput({
    // ...
    max: 500,
  });
  ```
</ParamField>

<ParamField body="precision" type="number" default={0}>
  The number of digits after the decimal point to use.

  ```js JavaScript icon=code theme={"system"}
  rangeInput({
    // ...
    precision: 2,
  });
  ```
</ParamField>

<ParamField body="templates" type="object">
  The [templates](#templates) to use for the widget.

  ```js JavaScript icon=code theme={"system"}
  rangeInput({
    // ...
    templates: {
      // ...
    },
  });
  ```
</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.
  * `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"],
    },
  });
  ```
</ParamField>

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

<Note>
  The `html` function is available in InstantSearch.js version 4.46.0 or later.
</Note>

<ParamField body="separatorText" type="string | function">
  The template for the separator, between the minimum and maximum inputs.

  <CodeGroup>
    ```js function theme={"system"}
    rangeInput({
      // ...
      templates: {
        separatorText(_, { html }) {
          return html`<span>to</span>`;
        },
      },
    });
    ```

    ```js string theme={"system"}
    // String-based templates are deprecated, use functions instead.
    rangeInput({
      // ...
      templates: {
        separatorText: "to",
      },
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="submitText" type="string | function">
  The template for the submit button.

  <CodeGroup>
    ```js function theme={"system"}
    rangeInput({
      // ...
      templates: {
        submitText(_, { html }) {
          return html`<span>Go</span>`;
        },
      },
    });
    ```

    ```js string theme={"system"}
    // String-based templates are deprecated, use functions instead.
    rangeInput({
      // ...
      templates: {
        submitText: "Go",
      },
    });
    ```
  </CodeGroup>
</ParamField>

## HTML output

```html HTML icon=code-xml theme={"system"}
<div class="ais-RangeInput">
  <form class="ais-RangeInput-form">
    <label class="ais-RangeInput-label">
      <input
        class="ais-RangeInput-input ais-RangeInput-input--min"
        type="number"
        placeholder=""
        step="1"
      />
    </label>
    <span class="ais-RangeInput-separator">to</span>
    <label class="ais-RangeInput-label">
      <input
        class="ais-RangeInput-input ais-RangeInput-input--max"
        type="number"
        placeholder=""
        step="1"
      />
    </label>
    <button class="ais-RangeInput-submit" type="submit">Go</button>
  </form>
</div>
```

## Customize the UI with `connectRange`

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

<Info>
  This connector is also used to build the [`rangeSlider`](/doc/api-reference/widgets/range-slider/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 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

<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 renderRangeInput = (renderOptions, isFirstRender) => {
    const { start } = renderOptions;
    const [min, max] = start;

    document.querySelector("#range-input").innerHTML = `
      <form>
        <input type="number" value="${Number.isFinite(min) ? min : ""}" />
        <span>to</span>
        <input type="number" value="${Number.isFinite(max) ? max : ""}" />
      </form>
    `;
  };
  ```
</ParamField>

<ParamField body="range" type="object">
  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 = `
      <form>
        <input type="number" placeholder="${range.min}" />
        <span>to</span>
        <input type="number" placeholder="${range.max}" />
      </form>
    `;
  };
  ```
</ParamField>

<ParamField body="canRefine" type="boolean" required>
  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;
    }
  };
  ```
</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 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 = `
      <input
        name="min"
        type="number"
        value="${Number.isFinite(min) ? min : ""}"
      />
      <span>to</span>
      <input
        name="max"
        type="number"
        value="${Number.isFinite(max) ? max : ""}"
      />
      <button>Go</button>
    `;
  };
  ```
</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 renderRangeInput = (renderOptions, isFirstRender) => {
    const { widgetParams } = renderOptions;

    widgetParams.container.innerHTML = "...";
  };

  // ...

  search.addWidgets([
    customRangeInput({
      container: document.querySelector("#range-input"),
    }),
  ]);
  ```
</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 customRangeInput = connectRange(renderRangeInput);

search.addWidgets([
  customRangeInput({
    attribute: string,
    // Optional parameters
    min: 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"}
  customRangeInput({
    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"}
  customRangeInput({
    // ...
    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"}
  customRangeInput({
    // ...
    max: 500,
  });
  ```
</ParamField>

<ParamField body="precision" type="number" default={0}>
  The number of digits after the decimal point to use.

  ```js JavaScript icon=code theme={"system"}
  customRangeInput({
    // ...
    precision: 2,
  });
  ```
</ParamField>

### Full example

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

  ```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 = `
      <input
        type="number"
        name="min"
        placeholder="${range.min}"
        value="${Number.isFinite(min) ? min : ""}"
      />
      <span>to</span>
      <input
        type="number"
        name="max"
        placeholder="${range.max}"
        value="${Number.isFinite(max) ? max : ""}"
      />
      <input type="submit" hidden />
    `;
  };

  // Create the custom widget
  const customRangeInput = connectRange(renderRangeInput);

  // Instantiate the custom widget
  search.addWidgets([
    customRangeInput({
      container: document.querySelector("#range-input"),
      attribute: "price",
    }),
  ]);
  ```
</CodeGroup>