> ## 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 = () =>
records
;
export const Index = () =>
index
;
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
FlavorSwitcher requires at least one option.
;
}
const selected = options.find(option => option.value === current) ?? options[0];
return ;
};
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/).
```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) setting.
The attribute values must be numbers, not strings.
## Examples
### Range slider with React Spectrum
```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 (
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 (
refine([start, end])}
isDisabled={!canRefine}
/>
);
}
```
Run and edit the useRange example in CodeSandbox.
### Range slider with Radix UI
```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 (
);
}
```
```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 (
refine([min, max]))}
disabled={!canRefine}
>
);
}
```
Run and edit the useRange example in CodeSandbox.
## Parameters
The name of the numeric attribute in your Algolia to use for refining the search.
```jsx JavaScript icon=code theme={"system"}
const rangeApi = useRange({
// ...
attribute: "price",
});
```
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,
});
```
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,
});
```
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,
});
```
## Returns
The selected range for the refinement,
where `start[0]` is the lower bound and `start[1]` is the higher bound.
The possible bounds based on the attribute's values.
Whether the search can be refined.
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.
Sends an event to the Insights API.