Skip to main content
Signature
rangeInput({
  container: string | HTMLElement,
  attribute: string,
  // Optional parameters
  min?: number,
  max?: number,
  precision?: number,
  templates?: object,
  cssClasses?: object,
});

Import

import { rangeInput } from "instantsearch.js/es/widgets";

About this widget

The rangeInput widget allows a user to select a numeric range using a minimum and maximum input.

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
rangeInput({
  container: "#range-input",
  attribute: "price",
});

Options

container
string | HTMLElement
required
The CSS Selector or HTMLElement to insert the widget into.
rangeInput({
  // ...
  container: "#range-input",
});
attribute
string
required
The name of the attribute in the record.
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 after the decimal point to use.
JavaScript
rangeInput({
  // ...
  precision: 2,
});
templates
object
The templates to use for the widget.
JavaScript
rangeInput({
  // ...
  templates: {
    // ...
  },
});
cssClasses
object
default:"{}"
The CSS classes you can override:
  • root. The root element of the widget.
  • form. The form element.
  • label. The label elements.
  • input. The input elements.
  • inputMin. The minimum input element.
  • inputMax. The maximum input element.
  • separator. The separator element.
  • submit. The submit button.
JavaScript
rangeInput({
  // ...
  cssClasses: {
    root: "MyCustomRangeInput",
    form: ["MyCustomRangeInputForm", "MyCustomRangeInputForm--subclass"],
  },
});

Templates

You can customize parts of a widget’s UI using the Templates API. Each template includes an html function, which you can use as a tagged template. This function safely renders templates as HTML strings and works directly in the browser—no build step required. For details, see Templating your UI.
The html function is available in InstantSearch.js version 4.46.0 or later.
separatorText
string | function
The template for the separator, between the minimum and maximum inputs.
rangeInput({
  // ...
  templates: {
    separatorText(_, { html }) {
      return html`<span>to</span>`;
    },
  },
});
submitText
string | function
The template for the submit button.
rangeInput({
  // ...
  templates: {
    submitText(_, { html }) {
      return html`<span>Go</span>`;
    },
  },
});

HTML output

HTML
<div class="ais-RangeInput">
  <form class="ais-RangeInput-form">
    <label class="ais-RangeInput-label">
      <input
        class="ais-RangeInput-input ais-RangeInput-input--min"
        type="number"
        placeholder=""
        step="1"
      />
    </label>
    <span class="ais-RangeInput-separator">to</span>
    <label class="ais-RangeInput-label">
      <input
        class="ais-RangeInput-input ais-RangeInput-input--max"
        type="number"
        placeholder=""
        step="1"
      />
    </label>
    <button class="ais-RangeInput-submit" type="submit">Go</button>
  </form>
</div>

Customize the UI with connectRange

If you want to create your own UI of the rangeInput widget, you can use connectors.
This connector is also used to build the rangeSlider widget.
To use connectRange, you can import it with the declaration relevant to how you installed InstantSearch.js.
import { connectRange } from "instantsearch.js/es/connectors";
Then it’s a 3-step process:
JavaScript
// 1. Create a render function
const renderRangeInput = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customRangeInput = connectRange(renderRangeInput);

// 3. Instantiate
search.addWidgets([
  customRangeInput({
    // instance params
  }),
]);

Create a render function

This rendering function is called before the first search (init lifecycle step) and each time results come back from Algolia (render lifecycle step).
JavaScript
const renderRangeInput = (renderOptions, isFirstRender) => {
  const { start, range, canRefine, refine, sendEvent, widgetParams } =
    renderOptions;

  if (isFirstRender) {
    // Do some initial rendering and bind events
  }

  // Render the widget
};

Rendering options

start
number[]
The current value for the refinement, with start[0] as the minimum value and start[1] as the maximum value.
JavaScript
const renderRangeInput = (renderOptions, isFirstRender) => {
  const { start } = renderOptions;
  const [min, max] = start;

  document.querySelector("#range-input").innerHTML = `
    <form>
      <input type="number" value="${Number.isFinite(min) ? min : ""}" />
      <span>to</span>
      <input type="number" value="${Number.isFinite(max) ? max : ""}" />
    </form>
  `;
};
range
object
The current available value for the range.
JavaScript
const renderRangeInput = (renderOptions, isFirstRender) => {
  const { range } = renderOptions;

  document.querySelector("#range-input").innerHTML = `
    <form>
      <input type="number" placeholder="${range.min}" />
      <span>to</span>
      <input type="number" placeholder="${range.max}" />
    </form>
  `;
};
canRefine
boolean
required
Indicates if search state can be refined.
JavaScript
const renderRangeInput = (renderOptions, isFirstRender) => {
  const { range, canRefine } = renderOptions;

  if (!canRefine) {
    document.querySelector("#range-input").innerHTML = "";
    return;
  }
};
refine
function
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 renderRangeInput = (renderOptions, isFirstRender) => {
  const { start, refine } = renderOptions;
  const [min, max] = start;

  const container = document.querySelector("#range-input");

  if (isFirstRender) {
    const form = document.createElement("form");

    form.addEventListener("submit", (event) => {
      event.preventDefault();

      const [minInput, maxInput] = event.target.elements;

      const rawMinInputValue = parseFloat(minInput.value);
      const rawMaxInputValue = parseFloat(maxInput.value);

      refine([
        Number.isFinite(rawMinInputValue) ? rawMinInputValue : undefined,
        Number.isFinite(rawMaxInputValue) ? rawMaxInputValue : undefined,
      ]);
    });

    container.appendChild(form);
  }

  container.querySelector("form").innerHTML = `
    <input
      name="min"
      type="number"
      value="${Number.isFinite(min) ? min : ""}"
    />
    <span>to</span>
    <input
      name="max"
      type="number"
      value="${Number.isFinite(max) ? max : ""}"
    />
    <button>Go</button>
  `;
};
sendEvent
(eventType, facetValue) => void
The function to send click events. The click event is automatically sent when refine is called. To learn more, see the insights middleware.
  • eventType: 'click'
  • facetValue: string
JavaScript
// For example,
sendEvent("click", [10, 30]);

/*
  A payload like the following will be sent to the `insights` middleware.
  {
    eventType: 'click',
    insightsMethod: 'clickedFilters',
    payload: {
      eventName: 'Filter Applied',
      filters: ['price>=10', 'price<=30'],
      index: '',
    },
    widgetType: 'ais.range',
  }
*/
widgetParams
object
All original widget options forwarded to the render function.
JavaScript
const renderRangeInput = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

  widgetParams.container.innerHTML = "...";
};

// ...

search.addWidgets([
  customRangeInput({
    container: document.querySelector("#range-input"),
  }),
]);

Create and instantiate the custom widget

First, create your custom widgets using a rendering function. Then, instantiate them with parameters. There are two kinds of parameters you can pass:
  • Instance parameters. Predefined options that configure Algolia’s behavior.
  • Custom parameters. Parameters you define to make the widget reusable and adaptable.
Inside the renderFunction, both instance and custom parameters are accessible through connector.widgetParams.
JavaScript
const customRangeInput = connectRange(renderRangeInput);

search.addWidgets([
  customRangeInput({
    attribute: string,
    // Optional parameters
    min: number,
    max: number,
    precision: number,
  }),
]);

Instance options

attribute
string
required
The name of the attribute in the record.
JavaScript
customRangeInput({
  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
customRangeInput({
  // ...
  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
customRangeInput({
  // ...
  max: 500,
});
precision
number
default:0
The number of digits after the decimal point to use.
JavaScript
customRangeInput({
  // ...
  precision: 2,
});

Full example

<div id="range-input"></div>
I