UI libraries / React InstantSearch / Widgets

<RangeInput>

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 
<RangeInput
  attribute={string}
  // Optional parameters
  min={number}
  max={number}
  precision={number}
  classNames={object}
  translations={object}
  ...props={ComponentProps<'div'>}
/>
Import
Copy 
1

import { RangeInput } from 'react-instantsearch';
See code examples
See live example

About this widget

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

You need to specify the attribute prop in attributes for faceting, either on the dashboard) or using attributesForFaceting with the API. The attribute values must be numbers, not strings.

You can also create your own UI with useRange().

Examples

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

import React from 'react';
import 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

Parameter Description
attribute
type: string
Required

The name of the attribute in the records.
Copy 
1

<RangeInput attribute="price" />
min
type: number

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

<RangeInput
  // ...
  min={10}
/>
max
type: number

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

<RangeInput
  // ...
  max={500}
/>
precision
type: number
default: 0

The number of digits to use after the decimal point.
Copy 
1
2
3
4

<RangeInput
  // ...
  precision={2}
/>
classNames
type: 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.
Copy 
1
2
3
4
5
6
7

<RangeInput
  // ...
  classNames={{
    root: 'MyCustomRangeInput',
    form: 'MyCustomRangeInputForm MyCustomRangeInputForm--subclass',
  }}
/>
translations
type: 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.
Copy 
1
2
3
4
5
6
7

<RangeInput
  // ...
  translations={{
    separatorElementText: '-',
    submitButtonText: 'Apply',
  }}
/>
...props
type: React.ComponentProps<'div'>

Any <div> prop to forward to the root element of the widget.
Copy 
1
2
3
4
5

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

See code examples

Usage

First, create your React component:

import { useRange } from 'react-instantsearch';

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

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

Then, render the widget:

<CustomRangeInput {...props} />

Parameters

Hooks accept parameters. You can pass them manually, or forward the props from your custom component.

When you provide a function to Hooks, make sure to pass a stable reference to avoid rendering endlessly (for example, with useCallback()). Objects and arrays are memoized; you don’t need to stabilize them.

Parameter Description
attribute
type: string
Required

The name of the attribute in the records.
Copy 
1
2
3

const rangeApi = useRange({
  attribute: 'price',
});
min
type: number

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

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

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

const rangeApi = useRange({
  // ...
  max: 500,
});
precision
type: number
default: 0

The number of digits to use after the decimal point.
Copy 
1
2
3
4

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.

Parameter Description
start
type: RangeBoundaries

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

Copy 
1
2
3
4

type RangeBoundaries = [
  number | undefined,
  number | undefined,
];
range
type: Range

The current available value for the range.

Copy 
1
2
3
4

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

Whether users can refine further.
refine
type: (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.

Copy 
1
2
3
4
5
6
7
8
9
10

const { refine } = useRange(props);

// ...

const onRangeSubmit = (min, max) => {
  refine([
    Number.isFinite(min) ? min : undefined,
    Number.isFinite(max) ? max: undefined,
  ]);
};
sendEvent
type: (eventType: string, facetValue: string, eventName?: string) => void

Sends an event to the Insights middleware.

Example

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
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

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());
}
Did you find this page helpful?
React InstantSearch v7