RangeInput

Lets users enter a numeric range for refining search results.

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

<RangeInput
  attribute={string}
  // Optional parameters
  min={number}
  max={number}
  precision={number}
  classNames={object}
  translations={object}
  ...props={ComponentProps<'div'>}
/>

Import

JavaScript

import { RangeInput } from "react-instantsearch";

See this widget in action

Preview this widget and its behavior.

About this widget

<RangeInput> is a widget to let users select a numeric range using minimum and maximum inputs.

You can also create your own UI with useRange.

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

JavaScript

import React from "react";
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { InstantSearch, RangeInput } from "react-instantsearch";

const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <RangeInput attribute="price" />
    </InstantSearch>
  );
}

Props

attribute · string · required

The name of the attribute in the .

JavaScript

<RangeInput attribute="price" />;

min · number

The minimum value for the input. When not provided, the minimum value is automatically computed by Algolia from the data in the index.

JavaScript

<RangeInput
  // ...
  min={10}
/>;

max · number

The maximum value for the input. When not provided, the maximum value is automatically computed by Algolia from the data in the .

JavaScript

<RangeInput
  // ...
  max={500}
/>;

precision · number · default: 0

The number of digits to use after the decimal point.

JavaScript

<RangeInput
  // ...
  precision={2}
/>;

classNames · Partial<RangeInputClassNames>

The CSS classes you can override and pass to the widget’s elements. It’s useful to style widgets with class-based CSS frameworks like Bootstrap or Tailwind CSS.

• root. The root element of the widget.
• noRefinementRoot. The root element when there are no refinements.
• form. The form element.
• label. Each label element.
• input. Each input element.
• inputMin. The minimum input element.
• inputMax. The maximum input element.
• separator. The separator element between inputs.
• submit. The submit button.

JavaScript

<RangeInput
  // ...
  classNames={{
    root: "MyCustomRangeInput",
    form: "MyCustomRangeInputForm MyCustomRangeInputForm--subclass",
  }}
/>;

translations · Partial<RangeInputTranslations>

A mapping of keys to translation values.

• separatorElementText. The text for the separator element between the minimum and maximum inputs.
• submitButtonText. The text for the submit button.

JavaScript

<RangeInput
  // ...
  translations={{
    separatorElementText: "-",
    submitButtonText: "Apply",
  }}
/>;

...props · React.ComponentProps<'div'>

Any <div> prop to forward to the root element of the widget.

JavaScript

<RangeInput
  // ...
  className="MyCustomRangeInput"
  title="My custom title"
/>;

Hook

React InstantSearch let you create your own UI for the <RangeInput> widget with useRange. Hooks provide APIs to access the widget state and interact with InstantSearch.

The useRange Hook accepts parameters and returns APIs. It must be used inside the <InstantSearch> component.

Usage

First, create your React component:

JavaScript

import { useRange } from "react-instantsearch";

function CustomRangeInput(props) {
  const { start, range, canRefine, refine, sendEvent } = useRange(props);

  return <>{/* Your JSX */}</>;
}

Then, render the widget:

JavaScript

<CustomRangeInput {...props} />

Parameters

Hooks accept parameters. You can either pass them manually or forward props from a custom component.

When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders. Use useCallback() for memoization. Arrays and objects are automatically memoized.

attribute · string · required

The name of the attribute in the records.

JavaScript

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

min · number

The minimum value for the input. When not provided, the minimum value is automatically computed by Algolia from the data in the index.

JavaScript

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

max · number

The maximum value for the input. When not provided, the maximum value is automatically computed by Algolia from the data in the index.

JavaScript

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

precision · number · default: 0

The number of digits to use after the decimal point.

JavaScript

const rangeApi = useRange({
  // ...
  precision: 2,
});

APIs

Hooks return APIs, such as state and functions. You can use them to build your UI and interact with React InstantSearch.

start · RangeBoundaries

The current value for the refinement, with start[0] as the minimum value and start[1] as the maximum value.

TypeScript

type RangeBoundaries = [number | undefined, number | undefined];

range · Range

The current available value for the range.

TypeScript

type Range = {
  min: number | undefined;
  max: number | undefined;
};

canRefine · boolean

Whether users can refine further.

refine · (rangeValue: RangeBoundaries) => 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.

JavaScript

const { refine } = useRange(props);

// ...

const onRangeSubmit = (min, max) => {
  refine([
    Number.isFinite(min) ? min : undefined,
    Number.isFinite(max) ? max : undefined,
  ]);
};

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

Sends an event to the Insights middleware.

Example

JavaScript

import React, { useState } from "react";
import { useRange } from "react-instantsearch";

const unsetNumberInputValue = "";

function CustomRangeInput(props) {
  const { start, range, canRefine, refine } = useRange(props);
  const step = 1 / Math.pow(10, props.precision || 0);
  const values = {
    min:
      start[0] !== -Infinity && start[0] !== range.min
        ? start[0]
        : unsetNumberInputValue,
    max:
      start[1] !== Infinity && start[1] !== range.max
        ? start[1]
        : unsetNumberInputValue,
  };
  const [prevValues, setPrevValues] = useState(values);

  const [{ from, to }, setRange] = useState({
    from: values.min?.toString(),
    to: values.max?.toString(),
  });

  if (values.min !== prevValues.min || values.max !== prevValues.max) {
    setRange({ from: values.min?.toString(), to: values.max?.toString() });
    setPrevValues(values);
  }

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();

        refine([from ? Number(from) : undefined, to ? Number(to) : undefined]);
      }}
    >
      <label>
        <input
          type="number"
          min={range.min}
          max={range.max}
          value={stripLeadingZeroFromInput(from || unsetNumberInputValue)}
          step={step}
          placeholder={range.min?.toString()}
          disabled={!canRefine}
          onInput={({ currentTarget }) => {
            const value = currentTarget.value;

            setRange({ from: value || unsetNumberInputValue, to });
          }}
        />
      </label>
      <span>to</span>
      <label>
        <input
          type="number"
          min={range.min}
          max={range.max}
          value={stripLeadingZeroFromInput(to || unsetNumberInputValue)}
          step={step}
          placeholder={range.max?.toString()}
          disabled={!canRefine}
          onInput={({ currentTarget }) => {
            const value = currentTarget.value;

            setRange({ from, to: value || unsetNumberInputValue });
          }}
        />
      </label>
      <button type="submit">Go</button>
    </form>
  );
}

function stripLeadingZeroFromInput(value) {
  return value.replace(/^(0+)\d/, (part) => Number(part).toString());
}

import React, { useState } from "react";
import { useRange, UseRangeProps } from "react-instantsearch";

const unsetNumberInputValue = "";

function CustomRangeInput(props: UseRangeProps) {
  const { start, range, canRefine, refine } = useRange(props);
  const step = 1 / Math.pow(10, props.precision || 0);
  const values = {
    min:
      start[0] !== -Infinity && start[0] !== range.min
        ? start[0]
        : unsetNumberInputValue,
    max:
      start[1] !== Infinity && start[1] !== range.max
        ? start[1]
        : unsetNumberInputValue,
  };
  const [prevValues, setPrevValues] = useState(values);

  const [{ from, to }, setRange] = useState({
    from: values.min?.toString(),
    to: values.max?.toString(),
  });

  if (values.min !== prevValues.min || values.max !== prevValues.max) {
    setRange({ from: values.min?.toString(), to: values.max?.toString() });
    setPrevValues(values);
  }

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();

        refine([from ? Number(from) : undefined, to ? Number(to) : undefined]);
      }}
    >
      <label>
        <input
          type="number"
          min={range.min}
          max={range.max}
          value={stripLeadingZeroFromInput(from || unsetNumberInputValue)}
          step={step}
          placeholder={range.min?.toString()}
          disabled={!canRefine}
          onInput={({ currentTarget }) => {
            const value = currentTarget.value;

            setRange({ from: value || unsetNumberInputValue, to });
          }}
        />
      </label>
      <span>to</span>
      <label>
        <input
          type="number"
          min={range.min}
          max={range.max}
          value={stripLeadingZeroFromInput(to || unsetNumberInputValue)}
          step={step}
          placeholder={range.max?.toString()}
          disabled={!canRefine}
          onInput={({ currentTarget }) => {
            const value = currentTarget.value;

            setRange({ from, to: value || unsetNumberInputValue });
          }}
        />
      </label>
      <button type="submit">Go</button>
    </form>
  );
}

function stripLeadingZeroFromInput(value: string): string {
  return value.replace(/^(0+)\d/, (part) => Number(part).toString());
}