> ## 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 Records = () => <Tooltip tip="A record is a searchable object in an Algolia index. Each record consists of named attributes." cta="Algolia records" href="/doc/guides/sending-and-managing-data/prepare-your-data#algolia-records">
    records
  </Tooltip>;

export const Index = () => <Tooltip tip="An Algolia index is a searchable dataset that consists of records and configuration settings. These settings define how the records are searched and ranked.">
    index
  </Tooltip>;

<Note>
  This is the **React InstantSearch v7** documentation.
  If you're upgrading from v6, see the [upgrade guide](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-v6-to-react-instantsearch-v7).
  If you were using React InstantSearch Hooks,
  this v7 documentation applies—just check for [necessary changes](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-hooks-to-react-instantsearch-v7).
  To continue using v6, you can find the [archived documentation](https://algolia.com/old-docs/deprecated/instantsearch/react/v6/api-reference/instantsearch/).
</Note>

```tsx Signature theme={"system"}
<RangeInput
  attribute={string}
  // Optional parameters
  min={number}
  max={number}
  precision={number}
  classNames={object}
  translations={object}
  ...props={ComponentProps<'div'>}
/>
```

## Import

```jsx JavaScript icon=code theme={"system"}
import { RangeInput } from "react-instantsearch";
```

<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

`<RangeInput>` is a widget to let users select a numeric range using minimum and maximum inputs.

<Tip>You can also create your own UI with [`useRange`](#hook).</Tip>

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

```jsx JavaScript icon=code theme={"system"}
import React from "react";
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { InstantSearch, RangeInput } from "react-instantsearch";

const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <RangeInput attribute="price" />
    </InstantSearch>
  );
}
```

## Props

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

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

  ```jsx 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 />.

  ```jsx JavaScript icon=code theme={"system"}
  <RangeInput
    // ...
    max={500}
  />;
  ```
</ParamField>

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

  ```jsx JavaScript icon=code theme={"system"}
  <RangeInput
    // ...
    precision={2}
  />;
  ```
</ParamField>

<ParamField body="classNames" type="Partial<RangeInputClassNames>">
  The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/react#style-your-widgets) and pass to the widget's elements.
  It's useful to style widgets with class-based CSS frameworks like [Bootstrap](https://getbootstrap.com) or [Tailwind CSS](https://tailwindcss.com).

  * `root`. The root element of the widget.
  * `noRefinementRoot`. The root element when there are no refinements.
  * `form`. The form element.
  * `label`. Each label element.
  * `input`. Each input element.
  * `inputMin`. The minimum input element.
  * `inputMax`. The maximum input element.
  * `separator`. The separator element between inputs.
  * `submit`. The submit button.

  ```jsx JavaScript icon=code theme={"system"}
  <RangeInput
    // ...
    classNames={{
      root: "MyCustomRangeInput",
      form: "MyCustomRangeInputForm MyCustomRangeInputForm--subclass",
    }}
  />;
  ```
</ParamField>

<ParamField body="translations" type="Partial<RangeInputTranslations>">
  A mapping of keys to translation values.

  * `separatorElementText`. The text for the separator element between the minimum and maximum inputs.
  * `submitButtonText`. The text for the submit button.

  ```jsx JavaScript icon=code theme={"system"}
  <RangeInput
    // ...
    translations={{
      separatorElementText: "-",
      submitButtonText: "Apply",
    }}
  />;
  ```
</ParamField>

<ParamField body="...props" type="React.ComponentProps<'div'>">
  Any `<div>` prop to forward to the root element of the widget.

  ```jsx JavaScript icon=code theme={"system"}
  <RangeInput
    // ...
    className="MyCustomRangeInput"
    title="My custom title"
  />;
  ```
</ParamField>

## Hook

React InstantSearch let you create your own UI for the `<RangeInput>` widget with `useRange`.
Hooks provide APIs to access the widget state and interact with InstantSearch.

The `useRange` Hook accepts [parameters](#parameters) and returns [APIs](#hook).
It must be used inside the [`<InstantSearch>`](/doc/api-reference/widgets/instantsearch/react) component.

### Usage

First, create your React component:

```jsx JavaScript icon=code theme={"system"}
import { useRange } from "react-instantsearch";

function CustomRangeInput(props) {
  const { start, range, canRefine, refine, sendEvent } = useRange(props);

  return <>{/* Your JSX */}</>;
}
```

Then, render the widget:

```jsx JavaScript icon=code theme={"system"}
<CustomRangeInput {...props} />
```

### Parameters

Hooks accept parameters. You can either pass them manually or forward props from a custom component.

<Note>
  When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders.
  Use [`useCallback()`](https://reactjs.org/docs/hooks-reference.html#usecallback) for memoization.
  Arrays and objects are automatically memoized.
</Note>

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

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

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

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

### APIs

Hooks return APIs, such as state and functions.
You can use them to build your UI and interact with React InstantSearch.

<ParamField body="start" type="RangeBoundaries">
  The current value for the refinement,
  with `start[0]` as the minimum value and `start[1]` as the maximum value.

  ```ts TypeScript icon=code theme={"system"}
  type RangeBoundaries = [number | undefined, number | undefined];
  ```
</ParamField>

<ParamField body="range" type="Range">
  The current available value for the range.

  ```ts TypeScript icon=code theme={"system"}
  type Range = {
    min: number | undefined;
    max: number | undefined;
  };
  ```
</ParamField>

<ParamField body="canRefine" type="boolean">
  Whether users can refine further.
</ParamField>

<ParamField body="refine" type="(rangeValue: RangeBoundaries) => void">
  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 { refine } = useRange(props);

  // ...

  const onRangeSubmit = (min, max) => {
    refine([
      Number.isFinite(min) ? min : undefined,
      Number.isFinite(max) ? max : undefined,
    ]);
  };
  ```
</ParamField>

<ParamField body="sendEvent" type="(eventType: string, facetValue: string, eventName?: string) => void">
  Sends an event to the Insights middleware.
</ParamField>

### Example

<CodeGroup>
  ```jsx JavaScript theme={"system"}
  import React, { useState } from "react";
  import { useRange } from "react-instantsearch";

  const unsetNumberInputValue = "";

  function CustomRangeInput(props) {
    const { start, range, canRefine, refine } = useRange(props);
    const step = 1 / Math.pow(10, props.precision || 0);
    const values = {
      min:
        start[0] !== -Infinity && start[0] !== range.min
          ? start[0]
          : unsetNumberInputValue,
      max:
        start[1] !== Infinity && start[1] !== range.max
          ? start[1]
          : unsetNumberInputValue,
    };
    const [prevValues, setPrevValues] = useState(values);

    const [{ from, to }, setRange] = useState({
      from: values.min?.toString(),
      to: values.max?.toString(),
    });

    if (values.min !== prevValues.min || values.max !== prevValues.max) {
      setRange({ from: values.min?.toString(), to: values.max?.toString() });
      setPrevValues(values);
    }

    return (
      <form
        onSubmit={(event) => {
          event.preventDefault();

          refine([from ? Number(from) : undefined, to ? Number(to) : undefined]);
        }}
      >
        <label>
          <input
            type="number"
            min={range.min}
            max={range.max}
            value={stripLeadingZeroFromInput(from || unsetNumberInputValue)}
            step={step}
            placeholder={range.min?.toString()}
            disabled={!canRefine}
            onInput={({ currentTarget }) => {
              const value = currentTarget.value;

              setRange({ from: value || unsetNumberInputValue, to });
            }}
          />
        </label>
        <span>to</span>
        <label>
          <input
            type="number"
            min={range.min}
            max={range.max}
            value={stripLeadingZeroFromInput(to || unsetNumberInputValue)}
            step={step}
            placeholder={range.max?.toString()}
            disabled={!canRefine}
            onInput={({ currentTarget }) => {
              const value = currentTarget.value;

              setRange({ from, to: value || unsetNumberInputValue });
            }}
          />
        </label>
        <button type="submit">Go</button>
      </form>
    );
  }

  function stripLeadingZeroFromInput(value) {
    return value.replace(/^(0+)\d/, (part) => Number(part).toString());
  }
  ```

  ```tsx TypeScript theme={"system"}
  import React, { useState } from "react";
  import { useRange, UseRangeProps } from "react-instantsearch";

  const unsetNumberInputValue = "";

  function CustomRangeInput(props: UseRangeProps) {
    const { start, range, canRefine, refine } = useRange(props);
    const step = 1 / Math.pow(10, props.precision || 0);
    const values = {
      min:
        start[0] !== -Infinity && start[0] !== range.min
          ? start[0]
          : unsetNumberInputValue,
      max:
        start[1] !== Infinity && start[1] !== range.max
          ? start[1]
          : unsetNumberInputValue,
    };
    const [prevValues, setPrevValues] = useState(values);

    const [{ from, to }, setRange] = useState({
      from: values.min?.toString(),
      to: values.max?.toString(),
    });

    if (values.min !== prevValues.min || values.max !== prevValues.max) {
      setRange({ from: values.min?.toString(), to: values.max?.toString() });
      setPrevValues(values);
    }

    return (
      <form
        onSubmit={(event) => {
          event.preventDefault();

          refine([from ? Number(from) : undefined, to ? Number(to) : undefined]);
        }}
      >
        <label>
          <input
            type="number"
            min={range.min}
            max={range.max}
            value={stripLeadingZeroFromInput(from || unsetNumberInputValue)}
            step={step}
            placeholder={range.min?.toString()}
            disabled={!canRefine}
            onInput={({ currentTarget }) => {
              const value = currentTarget.value;

              setRange({ from: value || unsetNumberInputValue, to });
            }}
          />
        </label>
        <span>to</span>
        <label>
          <input
            type="number"
            min={range.min}
            max={range.max}
            value={stripLeadingZeroFromInput(to || unsetNumberInputValue)}
            step={step}
            placeholder={range.max?.toString()}
            disabled={!canRefine}
            onInput={({ currentTarget }) => {
              const value = currentTarget.value;

              setRange({ from, to: value || unsetNumberInputValue });
            }}
          />
        </label>
        <button type="submit">Go</button>
      </form>
    );
  }

  function stripLeadingZeroFromInput(value: string): string {
    return value.replace(/^(0+)\d/, (part) => Number(part).toString());
  }
  ```
</CodeGroup>