🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
UI libraries / React InstantSearch / Widgets

useRange()

A

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

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

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

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

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