API Reference / React InstantSearch Hooks / <RangeInput>

<RangeInput>

Signature 
<RangeInput
  attribute={string}
  // Optional parameters
  min={number}
  max={number}
  precision={number}
  classNames={Partial<RangeInputClassNames>}
  ...props={React.ComponentProps<'div'>}
/>
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-hooks-web';

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

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

Props

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>

CSS classes to pass to the widget’s elements. This is 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',
  }}
/>
...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 Hooks 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-hooks-web';

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 with useCallback() to avoid rendering endlessly. Objects and arrays are memoized so you don’t have to stabilize them.

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.

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 the user can further refine.
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

import React from 'react';
import { useRange } from 'react-instantsearch-hooks-web';

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

  return <>{/* Your JSX */}</>;
}
Did you find this page helpful?
React InstantSearch Hooks v6