Dynamic Responsive Historic Timeline In jQuery

A simple yet fully customizable timeline jQuery plugin that takes events (stories, activities, etc) from JSON data and renders them in a responsive, vertical historic timeline interface based on years.

More Features:

• Allows multiple events in a year.
• Easy to implement without any JS call.
• Works with any JSON data.
• Event handlers.
• Allows to customize the appearance using your own CSS.

How to use it:

1. Load the timeline plugin's files after jQuery.

<link rel="stylesheet" href="/path/to/dist/jquery.timeline.min.css" />
<script src="/path/to/cdn/jquery.min.js"></script>
<script src="/path/to/dist/jquery.timeline.min.js"></script>

2. Define your events that consits of years, titles, images, descriptions, links as follows:

// data.json
{
  "2020": [
    {
      "title": "2020 Event 1",
      "image" : "1.jpg",
      "description": "Event Description 1",
      "link": "https://www.jqueryscript.net"
    },
    {
      "title": "2020 Event 2",
      "image" : "2.jpg",
      "description": "Event Description 2",
      "link": "https://www.jqueryscript.net"
    }
  ],
  "2019" : [
    {
      "title": "2019 Event 1",
      "image" : "3.jpg",
      "description": "Event Description 3",
      "link": "https://www.jqueryscript.net"
    },
    {
      "title": "2019 Event 2",
      "image" : "4.jpg",
      "description": "Event Description 4",
      "link": "https://www.jqueryscript.net"
    }
  ],
  ... more events here ...
}

3. Create a container to hold the timeline and specify the path to the JSON file in the data-timeline attribute. Done.

<div data-timeline="api.json"></div>

4. You can also initialize the plugin and render the data via JavaScript:

$("#timeline-container").timeline({
  apiUrl: 'api.json',
  container: '#timeline-container'
});

5. Determinr whether or not to use raw content. By default, the plugin uses .html() or .text() to prevent XSS attack. Use it at your own risk.

$("#timeline-container").timeline({
  allowRawContent: true
});

6. Format existing JSON data to fit the timeline structure.

// data-2.json
[
  {
      "year" : 2020,
      "caption": "2020 Event 1",
      "text": "Event Description 1",
      "url": "https://www.jqueryscript.net"
  },
  {
      "year" : 2020,
      "caption": "2020 Event 2",
      "text": "Event Description 2",
      "url": "https://www.jqueryscript.net"
  },
  ... more events here ...
]

const transforer = (data) => {
var transformed = {};

data.forEach(item => {
    if (!transformed[item.year]) transformed[item.year] = [];

    transformed[item.year].push({
        year: item.year,
        title: item.caption,
        description: item.text || null,
        link: item.url || null,
        image: item.img || null,
    });
});

  return transformed;
};

$(".timeline-container").timeline({
  container: '.timeline-container',
  apiUrl: 'data-2.json',
  transformer: transforer
});

$(".custom-transformer-timeline").on('timeline.after.generate', function () {
$(this).addClass('timeline'); 
});

7. Override the default styles to fit your web design.

/* Responsible for year label style */
.timeline-year-label { background: green } 

/* Responsible for timeline item title */
.timeline-item-title { color: gold; border-bottom: 1px dashed pink; }

/* Responsible for timeline line (center on desktop and left on mobile)*/
.timeline::before { background: #a101fd; }

/* Responsible for the image (if an item have one)*/
.timeline-item-image { border-radius: 100% }

/* Responsible for the description of an item */
.timeline-item-description  { color: blue; }

/* Responsible for the timeline "dot" at the end of line */
.timeline-end { background: #a101fd; border-radius: 100% }

8. Event handlers.

$('[data-timeline]').on('timeline.start', function (e) {
  // do something
});

$('[data-timeline]').on('timeline.ajax.before', function (e) {
  // do something
});

$('[data-timeline]').on('timeline.ajax.fail', function (e, jqXHR: jqXHR, textStatus: textStatus, errorThrown: errorThrown) {
  // do something
});

$('[data-timeline]').on('timeline.ajax.complete', function (e) {
  // do something
});

$('[data-timeline]').on('timeline.before.generate', function (e) {
  // do something
});

$('[data-timeline]').on('timeline.after.generate', function (e) {
  // do something
});

Changelog:

2020-06-16

• v1.0.6: update typo inside script

2020-05-13

• fix description css overflow when has a long string

---

This awesome jQuery plugin is developed by vsilva472. For more Advanced Usages, please check the demo page or visit the official website.