View on GitHub

timeline-range-slider

A customizable range slider with a built-in timeline

A lightweight, dependency-free range slider

The default configuration gives you a slider with a collapsible timeline:

Features & Benefits

Features:

Benefits:

Examples

#1: Default

#2: Dark theme

#3: Small and continuous

#4: Variable tick text

Usage

Installation

Pick what works for your setup:

  1. npm i @artoonie/timeline-range-slider
  2. Download assets from github package
  3. Just download the files in the timeline-range-slider directory. Go on. I won’t judge you.

Usage

API: Vanilla Javascript

If you’re not using node.js, functions begin with trs_ namespace to avoid conflicts:

Include the files in your HTML and create a wrapper div:

<link rel="stylesheet" href="slider.css">
<script type="text/javascript" src="slider.js"></script>
<div id="slide"></div>

Create a slider by calling:

const config = {wrapperDivId: 'slide', numTicks: 10}
trs_createSliderAndTimeline(config);

additional config options are described below.

You can a slider value manually by calling:

trs_setSliderValue('slide', 5);

You can animate a slider to have it move front-to-back with

trs_animate('slide');

Hide the timeline with:

trs_toggleTimelineVisibility('slide');

API: Using node.js

HTML:

const slider = require('./timeline-range-slider/slider.js');
require('./timeline-range-slider/slider.css');

<div id="slide"></div>

Javascript:

slider.createSliderAndTimeline(config);
slider.setSliderValue('slide', 5);
slider.animate('slide');
slider.toggleTimelineVisibility('slide');

Configuration options

The config dictionary has the following options:

key/default description
wrapperDivId*

required
The div id in which to place the slider
numTicks*

required
The number of elements in the slider
width

default: 600
The maximum width of the slider. If the page is narrower than this, the slider will responsively scale.
hideTimelineInitially

default: true
Whether or not the timeline is initially expanded or collapsed
tickLabelPrefix

default: 'Round '
What does each tick represent? Placed in the header row of the timeline.
hideActiveTickText

default: false
Should we hide tickText on the active tick? By default, we hide the text and show a slider via CSS. Only change this if you override the CSS for the active tick.
tickText

default: '•'
The text that marks a tick in the slider. Can be a single string or a list. If it’s a list, must be the size of numTicks.
color

default: 'orangered'
The color of past tick marks. Can be a single string or a list. If it’s a list, must be of size numTicks.
sliderValueChanged

default: null
Callback to be notified when the slider changes.
animateOnLoad

default: false
Should the slider animate all steps on load?
timeBetweenStepsMs

default: 1s/numTicks
How fast should the animation run?
timelinePeeking

default: true
Should the timeline “peek open” during animation, and close after the animation completes?
timelineData

default: random data
The timeline data. See below for how to structure this.
leftArrowText

default: <
What text to place in the left arrow button?
rightArrowText

default: <
What text to place in the right arrow button?

Timeline data structure

The timelineData contains the events that occurred at each “tick” in the timeline. It is a list of lists. Each of the numTicks elements contains a list of events. A single event is structured as follows:

const oneTimelineItem = {
  summaryText: "Short summary",

  /* optional */
  className: "custom-class-for-summary-label",

  /* optional */
  moreInfoText: "Description to show when hovering" 
}

Each “tick” can have multiple events (or zero events).

A complete timelineData structure might look like:

const timelineData = [
    [
        {summaryText: "Event 1, tick 1"},
        {summaryText: "Event 2, tick 1"}
    ],
    [
        {summaryText: "Event 1, tick 2",
         className: "some-class"}
    ],
    [ /* No events in tick 3 */
    ],
    [
        {summaryText: "Event 1, tick 4"},
        {summaryText: "Event 2, tick 4"},
        {summaryText: "Event 3, tick 4",
         moreInfoText: "a long description"}
    ]
]