rangeInput

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";

const { rangeInput } = instantsearch.widgets;
// or directly use instantsearch.widgets.rangeInput()

See this widget in action

Preview this widget and its behavior.

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",
});

rangeInput({
  // ...
  container: document.querySelector("#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>`;
    },
  },
});

// String-based templates are deprecated, use functions instead.
rangeInput({
  // ...
  templates: {
    separatorText: "to",
  },
});

submitText

string | function

The template for the submit button.

rangeInput({
  // ...
  templates: {
    submitText(_, { html }) {
      return html`<span>Go</span>`;
    },
  },
});

// String-based templates are deprecated, use functions instead.
rangeInput({
  // ...
  templates: {
    submitText: "Go",
  },
});

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";

const { connectRange } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectRange()

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',
  }
*/

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"),
  }),
]);

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>

// Create the render function
const renderRangeInput = (renderOptions, isFirstRender) => {
  const { start, range, refine, widgetParams } = renderOptions;
  const [min, max] = start;

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

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

      const rawMinInputValue = parseFloat(event.target.elements.min.value);
      const rawMaxInputValue = parseFloat(event.target.elements.max.value);

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

    widgetParams.container.appendChild(form);

    return;
  }

  widgetParams.container.querySelector("form").innerHTML = `
    <input
      type="number"
      name="min"
      placeholder="${range.min}"
      value="${Number.isFinite(min) ? min : ""}"
    />
    <span>to</span>
    <input
      type="number"
      name="max"
      placeholder="${range.max}"
      value="${Number.isFinite(max) ? max : ""}"
    />
    <input type="submit" hidden />
  `;
};

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

// Instantiate the custom widget
search.addWidgets([
  customRangeInput({
    container: document.querySelector("#range-input"),
    attribute: "price",
  }),
]);

InstantSearch.js

Import

See this widget in action

About this widget

Requirements

Examples

Options

Templates

HTML output

Customize the UI with `connectRange`

Create a render function

Rendering options

Create and instantiate the custom widget

Instance options

Full example

​Import

See this widget in action

​About this widget

​Requirements

​Examples

​Options

​Templates

​HTML output

​Customize the UI with connectRange

​Create a render function

​Rendering options

​Create and instantiate the custom widget

​Instance options

​Full example

Import

About this widget

Requirements

Examples

Options

Templates

HTML output

Customize the UI with `connectRange`

Create a render function

Rendering options

Create and instantiate the custom widget

Instance options

Full example