Skip to main content
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";
View demo

​
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 records.
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 index.
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

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

const unsetNumberInputValue = "";

function CustomRangeInput(props) {
  const { start, range, canRefine, precision, refine } = useRange(props);
  const step = 1 / Math.pow(10, 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());
}
⌘I