rangeSlider

Signature

rangeSlider({
  container: string | HTMLElement,
  attribute: string,
  // Optional parameters
  min?: number,
  max?: number,
  precision?: number,
  step?: number,
  pips?: boolean,
  tooltips?: boolean | object,
  cssClasses?: object,
});

Import

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

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

See this widget in action

Preview this widget and its behavior.

The rangeSlider widget provides a user-friendly way to filter the results, based on a single numeric range.

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

rangeSlider({
  container: "#range-slider",
  attribute: "price",
});

Options

container

string | HTMLElement

required

The CSS Selector or HTMLElement to insert the widget into.

rangeSlider({
  // ...
  container: "#range-slider",
});

rangeSlider({
  // ...
  container: document.querySelector("#range-slider"),
});

attribute

string

required

The name of the attribute in the record.

JavaScript

rangeSlider({
  // ...
  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

rangeSlider({
  // ...
  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

rangeSlider({
  // ...
  max: 500,
});

precision

number

default:0

The number of digits after the decimal point to use.Use a negative value to round values to powers of 10.For example, a precision of -2 would round a number to the nearest hundred, while a precision of -3 would round it to the nearest thousand.

JavaScript

// Round values to 2 digits after the decimal point
rangeSlider({
  // ...
  precision: 2,
});

// Round values to the nearest hundred
rangeSlider({
  // ...
  precision: -2,
});

step

number

The number of steps between each handle move.

JavaScript

rangeSlider({
  // ...
  step: 5,
});

pips

boolean

Whether to show slider pips.

JavaScript

rangeSlider({
  // ...
  pips: false,
});

tooltips

boolean | object

Whether to show tooltips. The default tooltips show the raw value. You can also provide an object with a format function.

rangeSlider({
  // ...
  tooltips: false,
});

rangeSlider({
  // ...
  tooltips: {
    format(value) {
      return `$${Math.round(value).toLocaleString()}`;
    },
  },
});

cssClasses

object

default:"{}"

The CSS classes you can override:

root. The root element of the widget.
handle. The handle elements.
lowerHandle. The handle for the minimum value.
upperHandle. The handle for the maximum value.
tooltip. The tooltip elements.

JavaScript

rangeSlider({
  // ...
  cssClasses: {
    root: "MyCustomrangeSlider",
    handle: [
      "MyCustomrangeSliderHandle",
      "MyCustomrangeSliderHandle--subclass",
    ],
  },
});

HTML output

HTML

<div class="ais-RangeSlider">
  <div class="rheostat rheostat-horizontal" style="position: relative;">
    <div class="rheostat-background"></div>
    <div
      class="rheostat-handle rehostat-handle--lower"
      aria-valuemax="5000"
      aria-valuemin="1"
      aria-valuenow="750"
      aria-disabled="false"
      data-handle-key="0"
      role="slider"
      tabindex="0"
      style="left: 15%; position: absolute;"
    >
      <div class="rheostat-tooltip">$750</div>
    </div>
    <div
      class="rheostat-handle rheostat-handle--upper"
      aria-valuemax="5000"
      aria-valuemin="750"
      aria-valuenow="5000"
      aria-disabled="false"
      data-handle-key="1"
      role="slider"
      tabindex="0"
      style="left: 100%; position: absolute;"
    >
      <div class="rheostat-tooltip">$5,000</div>
    </div>
    <div class="rheostat-progress" style="left: 15%; width: 85%;"></div>
    <div
      class="rheostat-marker rheostat-marker--large"
      style="left: 0%; position: absolute; margin-left: 0px;"
    >
      <div class="rheostat-value">1</div>
    </div>
    <div
      class="rheostat-marker"
      style="left: 2.94118%; position: absolute; margin-left: 0px;"
    ></div>
    <!-- ... -->
    <div
      class="rheostat-marker"
      style="left: 97.0588%; position: absolute; margin-left: 0px;"
    ></div>
    <div
      class="rheostat-marker rheostat-marker--large"
      style="left: 100%; position: absolute; margin-left: -1px;"
    >
      <div class="rheostat-value">5,000</div>
    </div>
  </div>
</div>

Customize the UI with `connectRange`

If you want to create your own UI of the rangeSlider widget, you can use connectors.

This connector is also used to build the rangeInput 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 renderRangeSlider = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customRangeSlider = connectRange(renderRangeSlider);

// 3. Instantiate
search.addWidgets([
  customRangeSlider({
    // 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 renderRangeSlider = (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 renderRangeSlider = (renderOptions, isFirstRender) => {
  const { start } = renderOptions;

  document.querySelector("#range-slider").innerHTML = `
    <input type="range" value="${Number.isFinite(start[0]) ? start[0] : "0"}" />
  `;
};

range

object

The current available value for the range.

JavaScript

const renderRangeSlider = (renderOptions, isFirstRender) => {
  const { start, range } = renderOptions;

  document.querySelector("#range-slider").innerHTML = `
    <input
      type="range"
      min="${range.min}"
      max="${range.max}"
      value="${Number.isFinite(start[0]) ? start[0] : "0"}"
    />
  `;
};

canRefine

boolean

required

Indicates if search state can be refined.

JavaScript

const renderRangeSlider = (renderOptions, isFirstRender) => {
  const { canRefine } = renderOptions;

  if (!canRefine) {
    document.querySelector("#range-slider").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 renderRangeSlider = (renderOptions, isFirstRender) => {
  const { start, range, refine } = renderOptions;
  const container = document.querySelector("#range-slider");

  if (isFirstRender) {
    const input = document.createElement("input");
    input.type = "range";

    input.addEventListener("change", (event) => {
      refine([parseFloat(event.currentTarget.value)]);
    });

    container.appendChild(input);

    return;
  }

  const input = container.querySelector("input");

  input.min = range.min;
  input.max = range.max;
  input.value = Number.isFinite(start[0]) ? start[0] : "0";
};

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 renderRangeSlider = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

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

// ...

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

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 customRangeSlider = connectRange(renderRangeSlider);

search.addWidgets([
  customRangeSlider({
    attribute: string, // Optional parametersmin:number,max:number,precision:number,
  }),
]);

Instance options

attribute

string

required

The name of the attribute in the record.

JavaScript

customRangeSlider({
  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

customRangeSlider({
  // ...
  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

customRangeSlider({
  // ...
  max: 500,
});

precision

number

default:0

JavaScript

// Round values to 2 digits after the decimal point
customRangeSlider({
  // ...
  precision: 2,
});

// Round values to the nearest hundred
customRangeSlider({
  // ...
  precision: -2,
});

Full example

<div id="range-slider"></div>

// Create the render function
const renderRangeSlider = (renderOptions, isFirstRender) => {
  const { start, range, refine, widgetParams } = renderOptions;

  if (isFirstRender) {
    const input = document.createElement("input");
    input.type = "range";

    input.addEventListener("change", (event) => {
      refine([parseFloat(event.currentTarget.value)]);
    });

    widgetParams.container.appendChild(input);

    return;
  }

  const input = widgetParams.container.querySelector("input");

  input.min = range.min;
  input.max = range.max;
  input.value = Number.isFinite(start[0]) ? start[0] : "0";
};

// Create the custom widget
const customRangeSlider = connectRange(renderRangeSlider);

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

InstantSearch.js

Import

See this widget in action

About this widget

Requirements

Examples

Options

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

​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

HTML output

Customize the UI with `connectRange`

Create a render function

Rendering options

Create and instantiate the custom widget

Instance options

Full example