> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# useRange

> React Hook for refining search results by a numeric range.

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>

```ts Signature theme={"system"}
const rangeApi = useRange({
  attribute: string,
  // Optional parameters
  min?: number,
  max?: number,
  precision?: number,
}
```

## Import

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

## About this Hook

Use this React Hook to filter search results within a numeric range.
You can build custom slider components with this Hook.

To display a number range input,
use the [`RangeInput`](/doc/api-reference/widgets/range-input/react) widget instead.

### Requirements

The [`attribute`](#param-attribute) provided to this Hook must be a facet,
which you can declare
in 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) <Index /> setting.

The attribute values must be numbers, not strings.

## Examples

### Range slider with React Spectrum

<CodeGroup>
  ```jsx JavaScript theme={"system"}
  import React, { useState, useEffect } from "react";
  import { useRange } from "react-instantsearch";
  import { RangeSlider as SpectrumRangeSlider } from "@adobe/react-spectrum";

  // …

  export function RangeSlider(props) {
    const { start, range, canRefine, refine } = useRange(props);
    const { min, max } = range;
    const [value, setValue] = useState({ start: min, end: max });

    const from = Math.max(min, Number.isFinite(start[0]) ? start[0] : min);
    const to = Math.min(max, Number.isFinite(start[1]) ? start[1] : max);

    useEffect(() => {
      setValue({ start: from, end: to });
    }, [from, to]);

    return (
      <SpectrumRangeSlider
        label="Price range"
        minValue={min}
        maxValue={max}
        value={value}
        onChange={setValue}
        onChangeEnd={({ start, end }) => refine([start, end])}
        isDisabled={!canRefine}
      />
    );
  }
  ```

  ```tsx TypeScript theme={"system"}
  import React, { useState, useEffect } from "react";
  import { useRange, type UseRangeProps } from "react-instantsearch";
  import { RangeSlider as SpectrumRangeSlider } from "@adobe/react-spectrum";

  // …

  export function RangeSlider(props: UseRangeProps) {
    const { start, range, canRefine, refine } = useRange(props);
    const min = (range.min as number) || 0;
    const max = (range.max as number) || 0;
    const [value, setValue] = useState({
      start: min,
      end: max,
    });

    const from = Math.max(min, Number.isFinite(start[0] as number) ? (start[0] as number): min);
    const to = Math.min(max, Number.isFinite(start[1] as number) ? (start[1] as number) : max);

    useEffect(() => {
      setValue({ start: from, end: to });
    }, [from, to]);

    return (
      <SpectrumRangeSlider
        label="Price range"
        minValue={min}
        maxValue={max}
        value={value}
        onChange={setValue}
        onChangeEnd={({ start, end }) => refine([start, end])}
        isDisabled={!canRefine}
      />
    );
  }
  ```
</CodeGroup>

<Card title="Open CodeSandbox" icon="codesandbox" href="https://codesandbox.io/s/github/algolia/doc-code-samples/tree/master/react-instantsearch/range-slider-with-react-spectrum?file=/src/RangeSlider.js">
  Run and edit the useRange example in CodeSandbox.
</Card>

### Range slider with Radix UI

<CodeGroup>
  ```tsx JavaScript theme={"system"}
  import React, { useState, useEffect } from "react";
  import { useRange } from "react-instantsearch";
  import { Slider } from "radix-ui";

  // …

  export function RangeSlider(props) {
    const { start, range, canRefine, refine } = useRange(props);
    const { min, max } = range;
    const [value, setValue] = useState([min, max]);

    const from = Math.max(min, Number.isFinite(start[0]) ? start[0] : min);
    const to = Math.min(max, Number.isFinite(start[1]) ? start[1] : max);

    useEffect(() => {
      setValue([from, to]);
    }, [from, to]);

    return (
      <Slider.Root
        min={min}
        max={max}
        value={value}
        onValueChange={setValue}
        onValueCommit={refine}
        disabled={!canRefine}
      >
        <Slider.Track>
          <Slider.Range />
        </Slider.Track>
        <Slider.Thumb />
        <Slider.Thumb />
      </Slider.Root>
    );
  }
  ```

  ```tsx TypeScript icon=code theme={"system"}
  import React, { useState, useEffect } from "react";
  import { Slider } from "radix-ui";

  // …

  export function RangeSlider(props: UseRangeProps) {
    const { start, range, canRefine, refine } = useRange(props);
    const min = (range.min as number) || 0;
    const max = (range.max as number) || 0;
    const [value, setValue] = useState([min, max]);

    const from = Math.max(
      min,
      Number.isFinite(start[0] as number) ? (start[0] as number) : min,
    );
    const to = Math.min(
      max,
      Number.isFinite(start[1] as number) ? (start[1] as number) : max,
    );

    useEffect(() => {
      setValue([from, to]);
    }, [from, to]);

    return (
      <Slider.Root
        min={min}
        max={max}
        value={value}
        onValueChange={setValue}
        onValueCommit={([min, max] => refine([min, max]))}
        disabled={!canRefine}
      >
        <Slider.Track>
          <Slider.Range />
        </Slider.Track>
        <Slider.Thumb />
        <Slider.Thumb />
      </Slider.Root>
    );
  }
  ```
</CodeGroup>

<Card title="Open CodeSandbox" icon="codesandbox" href="https://codesandbox.io/s/github/algolia/doc-code-samples/tree/master/react-instantsearch/range-slider-with-radix-ui?file=/src/RangeSlider.js">
  Run and edit the useRange example in CodeSandbox.
</Card>

## Parameters

<ParamField body="attribute" type="string" required>
  The name of the numeric attribute in your Algolia <Records /> to use for refining the search.

  ```jsx JavaScript icon=code theme={"system"}
  const rangeApi = useRange({
    // ...
    attribute: "price",
  });
  ```
</ParamField>

<ParamField body="min" type="number">
  The minimum value for the range.

  If not set,
  Algolia determines it based on the lowest value of the [`attribute`](#param-attribute) prop.

  ```jsx JavaScript icon=code theme={"system"}
  const rangeApi = useRange({
    // ...
    min: 10,
  });
  ```
</ParamField>

<ParamField body="max" type="number">
  The maximum value for the range.
  If not set,
  Algolia determines it based on the highest value of the [`attribute`](#param-attribute) prop.

  ```jsx JavaScript icon=code theme={"system"}
  const rangeApi = useRange({
    // ...
    max: 500,
  });
  ```
</ParamField>

<ParamField body="precision" type="number" default={0}>
  The number of decimal places to use when rounding values.
  Use negative values to round to powers of 10.

  ```jsx JavaScript icon=code theme={"system"}
  // Round values to 2 decimal places
  const rangeApi = useRange({
    // ...
    precision: 2,
  });

  // Round values to the nearest hundred
  const rangeApi = useRange({
    // ...
    precision: -2,
  });
  ```
</ParamField>

## Returns

<ResponseField name="start" type="[number, number]">
  The selected range for the refinement,
  where `start[0]` is the lower bound and `start[1]` is the higher bound.
</ResponseField>

<ResponseField name="range" type="{ min: number, max: number }">
  The possible bounds based on the attribute's values.
</ResponseField>

<ResponseField name="canRefine" type="boolean">
  Whether the search can be refined.
</ResponseField>

<ResponseField name="refine" type="(range: [number, number]) => void">
  Sets the range used to filter results.
  Use `undefined` to remove a bound or allow it to be unbounded.
  Both values are optional and default to the upper and lower bounds.
</ResponseField>

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