Tool Cool Range Slider

Responsive range slider library written in typescript and using web component technologies. Pure JavaScript without additional dependencies. It has a rich set of settings, including a vertical slider, touch, mousewheel and keyboard support, local and session storage, and RTL support.

• Responsive, touch, mousewheel, and keyboard support 📱
• Accessible via ARIA-attributes 🛡️
• ES6 JavaScript + TypeScript.
• No dependencies 🔓
• Predefined themes (optional) 🎨
• Customizable with a large set of style attributes 🔧
• Horizontal and vertical sliders support.
• Based on web component technologies.
• Allows programmatic attribute changes 💻
• Bottom to top support.
• Simple dynamic rendering after ajax requests or delays.
• Disabled / enabled range slider (including API).
• Local storage and session storage support 💾
• Supports a list of individual values (discrete values).
• Right to left (RTL) support.
• Text data support ✍️
• Non-linear range slider 📉
• Optional animation on panel click.
• Works well with Bootstrap and other CSS frameworks 👍
• No CSS conflicts due to web components.

Table of contents

• Basic usage
• CDN
• Node.js usage
• Main Properties
• List of individual values
• Width, Height, and Border Radius
• Predefined Styles (Themes)
• Colors
• Vertical Slider
• Pointer Shapes
• Touch & Keyboard Support
• Events
• Disabled
• Storage
• RTL Support
• Non-linear step
• Animation on panel click
• TypeScript Usage
• Usage with React and TypeScript
• License

Basic Usage

Download the latest toolcool-range-slider.min.js script:

Add the following html to the page:

<toolcool-range-slider>toolcool-range-slider>

<script type="text/javascript" src="toolcool-range-slider.min.js">script>

You can control the range slider by referencing the toolcool-range-slider HTML tag.

<toolcool-range-slider id="slider-1">toolcool-range-slider>

<script type="text/javascript" src="toolcool-range-slider.min.js">script>

<script>
    // get the reference
    const $slider = document.getElementById('slider-1');
    
    // change value
    $slider.value = 50;
    
    // get value
    console.log($slider.value);

    // listen to the change event
    $slider.addEventListener('change', (evt) => {
      const value = Math.round(evt.detail.value);
      console.log(value);
    });
script>

The value label can also be automatically bound using the value-label attribute:

<toolcool-range-slider value-label=".value-1">toolcool-range-slider>

<div class="value-1">div>

<script type="text/javascript" src="toolcool-range-slider.min.js">script>

📌 More examples with automatic label binding can be found here.

📌 Examples with js binding can be found here.

CDN

The ToolCool Range Slider is also available in the jsDelivr CND:

<toolcool-range-slider>toolcool-range-slider>

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/toolcool-range-slider/dist/toolcool-range-slider.min.js">script>

Node.js usage

Range slider may also be included as a node module using npm:

npm i toolcool-range-slider

or with Yarn:

yarn add toolcool-range-slider

And then you can include it in your application like this:

import 'toolcool-range-slider';

NPM package can fe found here.

Main Properties

Range slider has the following main properties: min, max, value, and step. All properties are optional, including step. Usage examples:

<toolcool-range-slider>toolcool-range-slider>

<toolcool-range-slider min="10" max="50">toolcool-range-slider>

<toolcool-range-slider min="-100" max="100" value="50">toolcool-range-slider>

<toolcool-range-slider min="0" max="100" value="50">toolcool-range-slider>

<toolcool-range-slider min="100" max="200" value="150" step="10">toolcool-range-slider>

The properties have the following default values:

If no value is specified, it will be equal to the minimum value.

List of individual values

It is also possible (but not required) to provide a list of numeric or text data instead of min and max properties.

ABC example:

<toolcool-range-slider
  data="a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z">toolcool-range-slider>

Geometric progression:

<toolcool-range-slider
data="2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192">toolcool-range-slider>

In the case where numeric and textual data is mixed, we assume that all data is textual.

📌 Example page can be found here.

Width, Height, and Border Radius

By default, the slider width is 100% and the height is 0.25 rem. These values can be changed using the slider-width and slider-height properties:

<toolcool-range-slider
        slider-width="300px"
        slider-height="15px"
        slider-radius="0.5rem">toolcool-range-slider>

<toolcool-range-slider
       slider-width="100%"
       slider-height="1rem">toolcool-range-slider>

Pointer width, height, and border-radius can be change using pointer-width, pointer-height, and pointer-radius properties:

<toolcool-range-slider
        pointer-width="35px"
        pointer-height="35px"
        pointer-radius="5px">toolcool-range-slider>

Default values table:

Predefined Styles (Themes)

The slider has several optional predefined themes. Each theme defines a unique look-and-feel and can be used "as is" without defining each style parameter separately.

All themes are fully optional and can be partially or completely replaced by custom styles, as described later in this documentation.

The slider has the following themes:

Usage examples:

<toolcool-range-slider
  slider-width="400px"
  slider-height="0.5rem"
  theme="rect">toolcool-range-slider>

It's possible to combine themes together with custom properties like this:

 <toolcool-range-slider
  slider-width="400px"
  slider-height="0.5rem"
  theme="rect"
  slider-bg="red">toolcool-range-slider>

Colors

Color and other styles can be customized with the following attributes:

<toolcool-range-slider
        slider-width="400px"
        slider-height="0.5rem"
        pointer-width="1.5rem"
        pointer-height="1.5rem"
        slider-bg="#6AD3BA"
        slider-bg-hover="#3F8A8A"
        pointer-border-hover="1px solid #79D6C0"
        pointer-border-focus="1px solid #79D6C0">toolcool-range-slider>


<toolcool-range-slider
          slider-width="400px"
          slider-height="0.5rem"
          pointer-width="1.5rem"
          pointer-height="1.5rem"
          pointer-bg="#6AD3BA"
          pointer-bg-hover="#50BDA3"
          pointer-shadow="none"
          pointer-shadow-hover="none"
          pointer-border="0"
          pointer-border-hover="1px solid #3F8A8A"
          pointer-border-focus="1px solid #3F8A8A">toolcool-range-slider>

The list of attributes and default values:

📌 An example of a customized slider on a dark background:

Vertical Slider

Vertical slider can be achieved using the type attribute as following:

<toolcool-range-slider type="vertical">toolcool-range-slider>

It accepts all the same attributes as the horizontal slider. The default height of a vertical slider is 300px unless the height attribute is provided.

It is also possible to reverse the direction and slide from bottom to top using the btt attribute:

<toolcool-range-slider type="vertical" btt="true">toolcool-range-slider>

Pointer Shapes

There are also several predefined pointer shapes that can be defined using the pointer-shape attribute. For example, triangle pointer shape:

<toolcool-range-slider
  min="0"
  max="100"
  value="10"
  pointer-shape="triangle"
  pointer-width="2rem"
  pointer-height="2rem"
  pointer-bg="#d7067d"
  pointer-bg-hover="#0b94c7"
  pointer-bg-focus="#0b94c7"
  slider-width="400px"
  slider-bg="#6787cd">toolcool-range-slider>

There are the following pointer shapes:

Touch & Keyboard Support

The library supports touch screens and also handles the following keys:

Events

The range slider has the following events:

Usage examples:

const $slider1 = document.getElementById('slider-1');

// change event ------------
$slider1.addEventListener('change', (evt) => {
    const value = Math.round(evt.detail.value);
    $value1.textContent = value.toString();
    console.log(`Change event: ${ value }`)
});

// onMouseDown event ------------
$slider1.addEventListener('onMouseDown', (evt) => {
    const nativeEvent = evt.detail.nativeEvent;
    console.log('Native mousedown event:', nativeEvent)
});

// onMouseUp event ------------
$slider1.addEventListener('onMouseUp', (evt) => {
    const nativeEvent = evt.detail.nativeEvent;
    console.log('Native mouseup event:', nativeEvent);
});

// onPointerClicked event ------------
$slider1.addEventListener('onPointerClicked', (evt) => {
    const $pointer = evt.detail.$pointer;
    console.log('Pointer clicked event:', $pointer);
});

// onKeyDownEvent event ------------
$slider1.addEventListener('onKeyDown', (evt) => {
    const nativeEvent = evt.detail.nativeEvent;
    console.log('Native onKeyDown event:', nativeEvent);
});

📌 The page with these examples can be found here.

Disabled

It's possible to disable the range slider using disabled attribute:

<toolcool-range-slider disabled="true">toolcool-range-slider>

This property can be easily toggled via APIs as follows:

const $slider1 = document.getElementById('slider-1');
const $toggleButton = document.getElementById('toggle-btn');

$toggleButton.addEventListener('click', () => {
  $slider1.disabled = !$slider1.disabled;
});

The default opacity of the range slider when disabled is 0.4. This value can be change using css variable --tc-range-slider-opacity:

<toolcool-range-slider
  disabled="true"
  style="--tc-range-slider-opacity: 0.1">toolcool-range-slider>

📌 The page with this example can be found here.

Storage

The range slider library also supports local and session storage. It's used to save the selected slider value between different pages and page reloads.

<toolcool-range-slider storage="session-storage" storage-key="tc-range-slider-1">toolcool-range-slider>
<toolcool-range-slider storage="local-storage" storage-key="tc-range-slider-2">toolcool-range-slider>

The difference between local and session storage is that session storage keeps the value only during the current session, while the local storage keeps it until the user clears the browser cache.

📌 The page with examples can be found here.

RTL support

The range slider also supports right to left (RTL) using rtl attribute as follows:

<toolcool-range-slider rtl="true">toolcool-range-slider>

<div class="row" style="direction: rtl">
  <label>0label>
  <toolcool-range-slider
    slider-width="100%"
    value-label=".value-1"
    rtl="true">toolcool-range-slider>
  <label>100label>
  <div class="value value-1">div>
div>