@kendawson-online/vantl

v2.0.6

Published

3 days ago

A vanilla JavaScript library that creates responsive timelines for both horizontal and vertical layouts

0High
0Medium
0Low

kendawson-online

timeline vanilla javascript ui

Vantl - Vanilla Timeline

Vantl is a lightweight, responsive timeline library created with vanilla Javascript for creating beautiful horizontal and vertical timelines with zero dependencies. Inspired by timeline originally created by squarechip in 2018.

Features

✨ Zero dependencies - Pure vanilla JavaScript (jQuery optional)
📱 Fully responsive - Auto-switches between horizontal/vertical layouts
🎨 Customizable colors - Theme nodes, lines, and navigation
🖼️ Rich content - Support for images, HTML, and modal popups
🔗 Deep linking - Link directly to specific timeline nodes via URL
📦 Multiple layouts - Vertical scroll or horizontal carousel modes
💾 Smart caching - LocalStorage caching for JSON data
🚀 Auto-init - Just add a data attribute to load from JSON
📏 Small footprint - Minified and tree-shakeable

Getting Started:

Load stylesheet and Javascript functions to your document via CDN links:

<!DOCTYPE html>
<html>
<head>
  <!-- load stylesheet -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@kendawson-online/vantl@2/dist/timeline.min.css">
</head>
<body>
   
  <!-- your timeline will go here --> 
  
  <!-- load functions -->
  <script src="https://cdn.jsdelivr.net/npm/@kendawson-online/vantl@2/dist/timeline.min.js"></script>
</body>
</html>

1️⃣ CREATE A TIMELINE USING BASIC HTML

Add some timeline node data in HTML. If you want your timeline to be oriented horizontally, set data-mode="horizontal" on the parent element (see code below). If you omit this setting, the timeline will be oriented vertically by default.

<!-- your timeline --> 
<div class="timeline" data-mode="horizontal">
  <div class="timeline__wrap">
    <div class="timeline__items">
        <div class="timeline__item">
            <div class="timeline__content">
                <h5>Jan. 1, 2000</h5>
                <p>Lorem ipsum dolor sit amet, qui minim labore adipisicing minim sint cillum.</p>
            </div>
        </div>
        <div class="timeline__item">
            <div class="timeline__content">
                <h5>Dec. 31, 2000</h5>
                <p>Lorem ipsum dolor sit amet, qui minim labore adipisicing minim sint cillum.</p>
            </div>
        </div>
        <div class="timeline__item">
            <div class="timeline__content">
                <h5>Jan. 1, 2001</h5>
                <p>Lorem ipsum dolor sit amet, qui minim labore adipisicing minim sint cillum.</p>
            </div>
        </div>
    </div>
  </div>
</div>

Add one line of code at the bottom to initialize your timeline. It goes after the CDN link but before the closing </body> tag and looks like this:

  <!-- load functions -->
  <script src="https://cdn.jsdelivr.net/npm/@kendawson-online/vantl@2/dist/timeline.min.js"></script>

  <!-- initialize the timeline -->
  <script>
    timeline(document.querySelectorAll('.timeline'));
  </script>

</body>
</html>

View A Basic HTML Example (With Source Code) 👀

Note: if you're using jQuery in your document, you can initialize your timeline like this:

    <!-- load functions -->
    <script src="https://cdn.jsdelivr.net/npm/@kendawson-online/vantl@2/dist/timeline.min.js"></script>

    <!-- initialize timeline with jQuery -->
    <script>
        jQuery(function () {
            $('.timeline').timeline({
              mode: 'horizontal'
            });
        });
    </script>

  </body>
</html>

For more info check the Advanced Usage section below

2️⃣ USE DATA ATTRIBUTES TO CUSTOMIZE YOUR TIMELINE

You can add data attributes to the timeline element to control how it looks and/or functions. For example, this is how you would set the orientation of the timeline to be horizontal instead of vertical (default):

<div class="timeline" data-mode="horizontal">
  ...
</div>

If you don't pass an attribute, the app will simply use the default values.

Here are the available data attributes:

| Option | Type | Default | Description | |--------|------|---------|-------------| | data-mode | string | 'vertical' | Layout mode: 'vertical' or 'horizontal' | | data-min-width | number | 600 | Minimum viewport width (px) to maintain horizontal mode | | data-max-width | number | 600 | Maximum viewport width (px) to maintain vertical mode | | data-visible-items | number | 3 | Number of items in horizontal viewport | | data-move-items | number | 1 | Items to scroll per navigation click (horizontal) | | data-start-index | number | 0 | Initial item index (horizontal mode) | | data-horizontal-start-position | string | 'top' | First item alignment in horizontal layout: 'top' or 'bottom' | | data-vertical-start-position | string | 'left' | First item alignment in vertical layout: 'left' or 'right' | | data-vertical-trigger | string | '15%' | Scroll trigger distance: percentage or px (e.g., '20%' or '150px') | | data-rtl-mode | boolean | false | Right to left mode: true or false (only works in horizontal mode and overrides startIndex setting) | | data-node-color | string | — | Node circle color (hex/rgb/hsl) | | data-line-color | string | — | Timeline line color (hex/rgb/hsl) | | data-nav-color | string | — | Navigation button color (hex/rgb/hsl) | | data-json-config | string | — | path to a JSON data file (e.g., /path/to/valid/file.json)|

See the API Documentation for a more detailed description of all options.

3️⃣ USING A JSON FILE TO LOAD TIMELINE DATA

A great way to use vanilla timeline is to store and load your data from an external JSON file. JSON stands for: "JavaScript Object Notation".

It's a lightweight text format stored in a file with a .json extension. It's easy for humans to read and write and for machines to parse and use in apps. JSON is based on a web standard so you have to follow the rules to produce "well-formed JSON" that is formatted a specific way. A simple JSON file might look something like this:

{
  "timelineName": "Timeline Title",
  "layoutMode": "horizontal",
  "visibleItems": 5,
  "minWidth": 700,
  "maxWidth": "",
  "nodeColor": "",
  "lineColor": "",
  "navColor": "",  
}

To use JSON, you add a data attribute called data-json-config to your HTML to tell the app which JSON file you want to load:

<div class="timeline" data-json-config="/path/to/timeline.json"></div>

⚠️ Important: if you set a data-json-config value, the app will prioritize JSON file settings and ignore any other data attribute values being passed inlne via HTML.

If you load your timeline data using the JSON method, you don't have to add the extra line of code at the bottom of the page (used to initialize the timeline). When a JSON file is loaded, the app is initialized automatically.

Here are some examples of JSON files you can use as templates to build your own timelines:

🗓️ A NOTE ABOUT DATES IN JSON 🗓️

If there are dates stored in these JSON files (e.g. the lastupdated field), they're stored in a special format named ISO 8601. The vanilla timeline app expects dates to be in this format.

There is a demo page included which displays this date format for you. This page also teaches you how to generate the ISO 8601 timestamp in the developer console of your web browser. Open the demo/time.html file in your browser to see a current ISO 8601 timestamp. You can copy/paste this date string directly into your JSON timelines.

Deep Linking

Link to a specific timeline node using URL parameters:

https://example.com/page.html?timeline=myTimelineId&id=3


https://[domain name]/[page name]?timeline=[timeline ID]&id=[node id]

Add an id attribute and value to your timeline container:

    <div id="myTimeline" class="timeline">
       ...
    </div>

Add a data-node-id to each node you want to link to

    <div class="timeline__items">
        <!-- node 1 -->
        <div class="timeline__item">
            <div class="timeline__content">
                <h5>Jan. 1, 2015</h5>
                <p>Lorem ipsum dolor sit amet, qui minim labore.</p>
            </div>
        </div>
        <!-- node 2 -->
        <div class="timeline__item">
            <div class="timeline__content">
                <h5>Dec. 31, 2016</h5>
                <p>Lorem ipsum dolor sit amet, qui minim labore.</p>
            </div>
        </div>
    </div>

Deep linking works automatically with JSON-loaded timelines

Advanced Usage:

Installing with npm

npm install @kendawson-online/vantl

Importing timeline functions into your Javscript app:

import { timeline } from '@kendawson-online/vantl';
import '@kendawson-online/vantl/dist/timeline.min.css';

timeline(document.querySelectorAll('.timeline'), {
  mode: 'vertical',
  nodeColor: '#2d6cdf'
});

Setting options

// vanilla Javascript
timeline(document.querySelectorAll('.timeline'), {
  mode: 'horizontal',
  visibleItems: 3,
});


// jQuery
$('.timeline').timeline({
  mode: 'vertical',
  verticalTrigger: '20%'
});

Available API Options

All options can be set via JavaScript API, data attributes, or with JSON config.

| Option | Type | Default | Description | |--------|------|---------|-------------| | mode | string | 'vertical' | Layout mode: 'vertical' or 'horizontal' | | minWidth | number | 600 | Min viewport width (px) to maintain horizontal mode | | maxWidth | number | 600 | Max viewport width (px) to maintain vertical mode | | visibleItems | number | 3 | Number of items in horizontal viewport | | moveItems | number | 1 | Items to scroll per navigation click (horizontal) | | startIndex | number | 0 | Initial item index (horizontal mode) | | horizontalStartPosition | string | 'top' | First item alignment: 'top' or 'bottom' | | verticalStartPosition | string | 'left' | First item alignment: 'left' or 'right' | | verticalTrigger | string | '15%' | Scroll trigger distance: percentage or px (e.g., '20%' or '150px') | | rtlMode | boolean | false | Right-to-left mode (horizontal) | | nodeColor | string | — | Node circle color (hex/rgb/hsl) | | lineColor | string | — | Center line color (hex/rgb/hsl) | | navColor | string | — | Navigation button color (hex/rgb/hsl) |

Custom Image Path

Override the auto-detected image path:

<script>
  window.TimelineConfig = {
    basePath: '/custom/path/to/images'
  };
</script>
<script src="dist/timeline.min.js"></script>

Programmatic control

// Load from JSON programmatically
loadDataFromJson('/data/timeline.json', '#myTimeline');

// Clear cache
clearTimelineCache();             // Clear all
clearTimelineCache('timelineId'); // Clear specific

// Navigate to node (horizontal mode)
navigateTimelineToNodeIndex(containerElement, 5);

// Open modal
openTimelineModal(itemElement);

// Close modal
closeTimelineModal();

More Information

Browser Support

Chrome/Edge (2018+)
Firefox (2018+)
Safari (2018+)
Requires: ES6, IntersectionObserver, CSS Custom Properties

Contributing

See Development.md for build instructions and an architectural overview.

See API Documentation for details about how the API works.

You can report issues and open pull requests on GitHub:

https://github.com/kendawson-online/vantl/issues
https://github.com/kendawson-online/vantl/pulls

Links

NPM Package: @kendawson-online/vantl

Repository: github.com/kendawson-online/vantl

CDN: cdn.jsdelivr.net/npm/@kendawson-online/vantl

License

MIT License

Credits

Originally inspired by timeline by Mike Collins (2018).

Refactored and maintained by Ken Dawson (2026).

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Vantl - Vanilla Timeline

Features

Getting Started:

1️⃣ CREATE A TIMELINE USING BASIC HTML

View A Basic HTML Example (With Source Code) 👀

2️⃣ USE DATA ATTRIBUTES TO CUSTOMIZE YOUR TIMELINE

3️⃣ USING A JSON FILE TO LOAD TIMELINE DATA

Deep Linking

Advanced Usage:

Installing with npm

Setting options

Available API Options

Custom Image Path

Programmatic control

More Information

Browser Support

Contributing

Links

License

Credits