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 one and two pointers, a vertical slider, touch, mousewheel and keyboard support, local and session storage, and RTL support.

• Responsive, touch, mousewheel, and keyboard support 📱
• Range slider with one or two pointers.
• 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.
• Automatically generated labels (optional).
• Supports multiple sliders on one page.
• Supports two pointers overlap, pointers max and min distance.

Table of contents

• Basic usage
• CDN
• Node.js usage
• Main Properties
• List of individual values
• Width, Height, and Border Radius
• Automatically generated labels
• Predefined Styles (Themes)
• Colors
• Vertical Slider
• Pointer Shapes
• Touch & Keyboard Support
• Events
• Disabled
• Storage
• RTL Support
• Non-linear step
• Pointers overlap
• Pointers max and min distance
• 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>

Range slider with two pointers can be created by adding the value2 parameter:

<toolcool-range-slider min="0" max="100" value="30" value2="60"></toolcool-range-slider>

It's also possible to use value1 instead of value:

<toolcool-range-slider min="0" max="100" value1="30" value2="60"></toolcool-range-slider>

value1 is just an alias of the value property.

⭐ It's also possible to generate min, max, and value labels automatically. Click here for more details.

📌 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" round="0"></toolcool-range-slider>

<toolcool-range-slider value1="10" value2="20"></toolcool-range-slider>

<toolcool-range-slider min="-200" max="200" value1="-50" value2="100"></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:

Automatically generated labels

It's possible to generate min, max, and value labels automatically using generate-labels="true" attribute:

<toolcool-range-slider generate-labels="true"></toolcool-range-slider>

If this attribute is specified, the minimum, maximum, and value label are automatically generated.

You can provide custom html for all or part of the labels:

<toolcool-range-slider generate-labels="true">
  <div slot="min-label"><label class="min-label"></label> px</div>
  <div slot="max-label"><label class="max-label"></label> px</div>
  <div slot="value-label"><label class="value-label"></label> px</div>
</toolcool-range-slider>

This way you can add CSS classes, inline styles, or any HTML structure instead of the standard range slider labels.

❗ Please make sure you keep slot names with one of the following values: min-label, max-label, value-label.

❗ It's also important, that the labels have one of the following classes: min-label, max-label, value-label. These classes are used as placeholders for min, max, and value.

Other than that, the HTML structure can be changed in any way.

📌 Example page can be found here.

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>0</label>
  <toolcool-range-slider
    slider-width="100%"
    value-label=".value-1"
    rtl="true"></toolcool-range-slider>
  <label>100</label>
  <div class="value value-1"></div>
</div>

📌 The page with examples can be found here.

Non-linear step

The range slider supports the non-linear step function. For example, the slider below has a step of 5 if the value is less than 50, otherwise the step is 10:

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

<script src="toolcool-range-slider.min.js"></script>
<script>
    const $slider = document.getElementById('slider-1');
    $slider.step = (value) => {
        return value < 50 ? 5 : 10;
    };
</script>

Step function has the following type:

(value: number | string) => number

It gets the value of the slider and returns the corresponding step value.

📌 The page with examples can be found here.

Pointers overlap

In the two pointer range slider, pointer overlap can be enabled using pointers-overlap attribute:

<toolcool-range-slider pointers-overlap="true" value1="10" value2="40" min="0" max="100"></toolcool-range-slider>

There is also a corresponding API property:

const $slider = document.querySelector('#slider');
$slider.pointersOverlap = true;

Pointers max and min distance

In the two pointer range slider, it's possible to define the minimum required distance between the pointers using pointers-min-distance attribute:

<toolcool-range-slider
  generate-labels="true"
  round="0"
  value1="30"
  value2="60"
  pointers-min-distance="4"
  slider-width="100%"></toolcool-range-slider>

It is also possible to define the maximum distance between two pointers using the pointers-max-distance attribute:

<toolcool-range-slider
  generate-labels="true"
  round="0"
  value1="30"
  value2="60"
  pointers-max-distance="50"
  slider-width="100%"></toolcool-range-slider>

There is also a corresponding API properties:

const $slider = document.querySelector('#slider');
$slider.pointersMinDistance = 5;
$slider.pointersMaxDistance = 50;

Please note that the provided distances should be >= 0;

The properties have the following default values:

📌 The page with examples can be found here.

Animation on panel click

It's possible to enable animation on panel click with the animate-onclick property:

<toolcool-range-slider animate-onclick="0.3s"></toolcool-range-slider>

The value of the animate-onclick property is specified in seconds, ms, etc. and is the same as the css transition-duration property.

📌 The page with example can be found here.

TypeScript Usage

import 'toolcool-range-slider';
import RangeSlider from 'toolcool-range-slider';

// ...

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

$slider.addEventListener('change', (evt: Event) => {
    const customEvent = evt as CustomEvent;
    const value = Math.round(evt.detail.value);
    console.log(value);
});

$slider.value = 10;

Usage with React and TypeScript

import 'toolcool-range-slider';

declare global {
    namespace JSX {
        interface IntrinsicElements {
            'toolcool-range-slider': any;
        }
    }
}

const RangeSliderExample = () => {

    const rangeSliderRef = useRef<HTMLElement>();

    useEffect(() => {

        const slider = rangeSliderRef.current;

        const onChange = (evt: Event) => {
            const customEvent = evt as CustomEvent;
            const value = Math.round(evt.detail.value);
            console.log(value);
        };

        slider?.addEventListener('change', onChange);

        return () => {
          slider?.removeEventListener('change', onChange);
        };
    }, []);

    return (
        <toolcool-range-slider ref={ rangeSliderRef } />;
    )
};

export default RangeSliderExample;

License

MIT license

It can be used for free in any personal or commercial project 🎁