UI libraries / React InstantSearch / Widgets

useRange()

This is the React InstantSearch v7 documentation. React InstantSearch v7 is the latest version of React InstantSearch and the stable version of React InstantSearch Hooks.

If you were using React InstantSearch v6, you can upgrade to v7.

If you were using React InstantSearch Hooks, you can still use the React InstantSearch v7 documentation, but you should check the upgrade guide for necessary changes.

If you want to keep using React InstantSearch v6, you can find the archived documentation.

Signature 
const rangeApi = useRange({
  attribute: string,
  // Optional parameters
  min: number,
  max: number,
  precision: number,
}
Import
Copy 
1

import { useRange } from 'react-instantsearch';
See code examples
See live example

About this Hook

React Hook to filter search results within a numeric range. With this Hook, you can build your own slider components.

The Examples section includes examples for two popular React UI components libraries.

To display an input for a range of numbers, use the <RangeInput> widget instead.

Requirements

The attribute must be set as an attribute for faceting. You can do that in the dashboard or with the API.

Examples

Range slider with React Spectrum

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

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}
    />
  );
}
Live Demo

Range slider with Radix UI

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

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>
  );
}
Live Demo

Parameters

Parameter Description
attribute
type: string
Required

The name of a numeric attribute in your Algolia records which should be used for refining the search.
Copy 
1
2
3
4

const rangeApi = useRange({
  // ...
  attribute: 'price',
});
min
type: number
Optional

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.
Copy 
1
2
3
4

const rangeApi = useRange({
  // ...
  min: 10,
});
max
type: number
Optional

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.
Copy 
1
2
3
4

const rangeApi = useRange({
  // ...
  max: 500,
});
precision
type: number
default: 0
Optional

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.
Copy 
1
2
3
4
5
6
7
8
9
10
11

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

Parameter Description
start
type: [number, number]

The selected range for the refinement, with start[0] as the lower bound and start[1] as the higher bound.
range
type: { min: number, max: number }

The highest and lowest possible bounds for the range.
canRefine
type: boolean

Whether the search can be refined.
refine
type: (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
type: (eventType: string, facetValue: string, eventName?: string) => void

Sends an event to the Insights API.
Did you find this page helpful?
React InstantSearch v7