Timeliner: a designer-friendly javascript timeline drawing tool

Timeliner is a simple javascript timeline drawing tool aimed at easy visual customization: you should be able to obtain the visual appearance you want using only the provided parameters and some css; and for cases where you need to edit the library code directly it should be plain and short enough to do it without hassle.

A timeline is composed of 2 elements: - the main component where the events are displayed, often it’s larger than the screen - an overview displaying the full time range on one screen using icons for the events with a highlighted zone that indicates the part displayed on the main view

A Quick Example

You can draw a simple timeline by providing: * the events * the main component where they should be displayed * an optional element to display the overview

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    <title>TimeLiner sample</title>
    <script src="timeliner/jquery-1.4.4.min.js" type="text/javascript">
    <script src="timeliner/jquery.mousewheel.min.js" type="text/javascript">
    <script src="timeliner/jquery.scrollTo-1.4.2-min.js" type="text/javascript">
    <script src="timeliner/timeliner.js" type="text/javascript">
    <link rel="stylesheet" href="timeliner/timeliner-structure.css" type="text/css">
    <link rel="stylesheet" href="timeliner/timeliner-custom.css" type="text/css">

    <style type="text/css">
        #title {
            text-align: center;

        #myMainTimeLine {
            width: 100%;
            height: 400px;
            background-color: #eeeeee;
        #myOverviewTimeLine {
            width: 100%;
            height: 25px;
            padding-top: 10px;
            background-color: #f5f5f5;
            font-size: 10px;
    <script type="text/javascript">
        $(function() {
            var events = [
                {"date": new Date(2001, 1, 0),
                    "content": "first event !"},
                {"date": new Date(2001, 5, 10),
                    "content": "another event"},
                {"date": new Date(2001, 2, 5),
                    "content": "a third event<br>on two lines"},
                {"date": new Date(2001, 4, 15),
                    "content": "another one"},
                {"date": new Date(2010, 1, 5),
                    "content": "event"},
                {"date": new Date(2012, 5, 5),
                    "content": "again"},
                {"date": new Date(2012, 11, 31),
                    "content": "a last one"}
            new TimeLiner(
                {"events" : events,
                "mainTimeLinerSelector": "#myMainTimeLine",
                "overviewTimeLinerSelector": "#myOverviewTimeLine"});
<h1 id="title">TimeLine sample</h1>

<div id="myMainTimeLine"></div>
<div id="myOverviewTimeLine"></div>

More elaborate examples:

TODO: add examples when they’ll be published

How it works

When a timeline is instantiated, each element is created at its target horizontal position according to its date, then moved down until we find a space large enough to not overlay with existing events.

AS elements are created using the order they are provided in the parameters the first elements will be displayed above the following ones. This can be used to choose which elements should be emphasized by being on the timeline’s top.

On external resources:

As the timeline is created as soon as the DOM is ready you must:

Because when the events’ positions is calculated the images and font may not have been downloaded yet, you have to provide the browser enough information to calculate the elements size without these resources, or instead the display would be wrong.

Available Parameters and usages

Required Parameters

Optional parameters

Advanced parameters:

The 3 last parameters are used when you need the time scale to change along the timeline and should be used together.

For example if you want the years to use more widths after a certain date:

var normalYearWidth = 75;
var extendedYearWidth = 300;
var switchYear = 2008;

new TimeLiner({
    // ...
    "numberOfPixelsForYear": function(params, year) {
        return (year <= switchYear) ? normalYearWidth : extendedYearWidth;
    "dateToNumberOfPixels": function(params, minYear, date) {
        if (date.getFullYear() <= switchYear) {
            return Math.ceil((date.getFullYear() - minYear + (date.getDOY() / 365)) * normalYearWidth);
        } else {
            var numberOfPixelsBeforeSwitch = ((switchYear - (minYear - 1)) * normalYearWidth);
            return numberOfPixelsBeforeSwitch + Math.ceil((date.getFullYear() - (switchYear + 1 ) + (date.getDOY() / 365)) * extendedYearWidth)
    "numberOfPixelsToDate": function(params, minYear, pixelsNumber) {
        var numberOfPixelsBeforeSwitch = ((switchYear - (minYear - 1)) * normalYearWidth);
        if (pixelsNumber < numberOfPixelsBeforeSwitch) {
            return new Date((minYear + (pixelsNumber / normalYearWidth) - 1970) * TimeLiner.SECONDS_IN_A_YEAR);
        } else {

            return new Date((((pixelsNumber - numberOfPixelsBeforeSwitch ) / extendedYearWidth) + (switchYear - 1969)) * TimeLiner.SECONDS_IN_A_YEAR);

HTML Elements for CSS customization

Here are the HTML created by the timelines:

The timeliner-custom.css file contain some default formatting for them, you can use this file to start working on your markup.


It relies on:


It is being tested on Firefox, Internet Explorer, Opera & Safari on Windows and Mac Os.