useRange

React Hook for refining search results by a numeric range.

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

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 widget instead.

Requirements

The attribute provided to this Hook must be a facet, which you can declare in the dashboard or using the attributesForFaceting index setting.

The attribute values must be numbers, not strings.

Examples

Range slider with React Spectrum

JavaScript

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

JavaScript

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

View demo

Parameters

attribute · string · required

The name of the numeric attribute in your Algolia records to use for refining the search.

JavaScript

const rangeApi = useRange({
  // ...
  attribute: "price",
});

min · number

The minimum value for the range.

If not set, Algolia determines it based on the lowest value of the attribute prop.

JavaScript

const rangeApi = useRange({
  // ...
  min: 10,
});

max · number

The maximum value for the range. If not set, Algolia determines it based on the highest value of the attribute prop.

JavaScript

const rangeApi = useRange({
  // ...
  max: 500,
});

precision · number · default: 0

The number of decimal places to use when rounding values. Use negative values to round to powers of 10.

JavaScript

// Round values to 2 decimal places
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, where start[0] is the lower bound and start[1] is the higher bound.

range · { min: number, max: number }

The possible bounds based on the attribute’s values.

canRefine · boolean

Whether the search can be refined.

refine · (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.

sendEvent · (eventType: string, facetValue: string, eventName?: string) => void

Sends an event to the Insights API.