useRange - Algolia

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 setting. The attribute values 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}
    />
  );
}

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 (
    <SpectrumRangeSlider
      label="Price range"
      minValue={min}
      maxValue={max}
      value={value}
      onChange={setValue}
      onChangeEnd={({ start, end }) => refine([start, end])}
      isDisabled={!canRefine}
    />
  );
}

Open CodeSandbox

Run and edit the useRange example in CodeSandbox.

Range slider with Radix UI

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

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 (
    <Slider.Root
      min={min}
      max={max}
      value={value}
      onValueChange={setValue}
      onValueCommit={([min, max] => refine([min, max]))}
      disabled={!canRefine}
    >
      <Slider.Track>
        <Slider.Range />
      </Slider.Track>
      <Slider.Thumb />
      <Slider.Thumb />
    </Slider.Root>
  );
}

Open CodeSandbox

Run and edit the useRange example in CodeSandbox.

Parameters

string

required

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

JavaScript

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

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

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

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

[number, number]

The selected range for the refinement, where start[0] is the lower bound and start[1] is the higher bound.

{ min: number, max: number }

The possible bounds based on the attribute’s values.

boolean

Whether the search can be refined.

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

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

Sends an event to the Insights API.

​Import

​About this Hook

​Requirements

​Examples

​Range slider with React Spectrum

Open CodeSandbox

​Range slider with Radix UI

Open CodeSandbox

​Parameters

​Returns

Import

About this Hook

Requirements

Examples

Range slider with React Spectrum

Range slider with Radix UI

Parameters

Returns