Skip to main content
This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.
Signature
const rangeApi = useRange({
  attribute: string,
  // Optional parameters
  min?: number,
  max?: number,
  precision?: number,
}

​
Import

JavaScript
import { useRange } from "react-instantsearch";

​
About this Hook

React Hook to filter search results within a numeric range. With this Hook, you can build your own slider components. To display an input for a range of numbers, use the <RangeInput> widget instead.

​
Requirements

The attribute provided to the widget must be in attributes for faceting, either on the dashboard or using the attributesForFaceting parameter with the API. The values of the attribute must be numbers, not strings.

​
Examples

​
Range slider with React Spectrum

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}
    />
  );
}
View demo

​
Range slider with Radix UI

import React, { useState, useEffect } from "react";
import { useRange } from 'react-instantsearch';
import * as Slider from '@radix-ui/react-slider';

// …

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>
  );
}
View demo

​
Parameters

​
attribute
string
required
The name of a numeric attribute in your Algolia records which should be used for refining the search.
JavaScript
const rangeApi = useRange({
  // ...
  attribute: "price",
});
​
min
number
The minimum value for the input.When not provided, Algolia determines the minimum from the values of the attribute you specified in the attribute prop.
JavaScript
const rangeApi = useRange({
  // ...
  min: 10,
});
​
max
number
The maximum value for the input.When not provided, Algolia determines the maximum from the values of the attribute you specified in the attribute prop.
JavaScript
const rangeApi = useRange({
  // ...
  max: 500,
});
​
precision
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.
JavaScript
// Round values to 2 digits after the decimal point
const rangeApi = useRange({
  // ...
  precision: 2,
});

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

​
Returns

​
start
[number, number]
The selected range for the refinement, with start[0] as the lower bound and start[1] as the higher bound.
​
range
{ min: number, max: number }
The highest and lowest possible bounds for the range.
​
canRefine
boolean
Whether the search can be refined.
​
refine
(range: [number, number]) => 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.
​
sendEvent
(eventType: string, facetValue: string, eventName?: string) => void
Sends an event to the Insights API.
⌘I