Timeline documentation

Author Jos de Jong, Almende B.V.
Webpage http://visjs.org
License Apache License, Version 2.0

Contents

Overview

The Timeline is an interactive visualization chart to visualize data in time. The data items can take place on a single date, or have a start and end date (a range). You can freely move and zoom in the timeline by dragging and scrolling in the Timeline. Items can be created, edited, and deleted in the timeline. The time scale on the axis is adjusted automatically, and supports scales ranging from milliseconds to years.

Example

The following code shows how to create a Timeline and provide it with data. More examples can be found in the examples directory. 

<!DOCTYPE HTML>
<html>
<head>
    <title>Timeline | Basic demo</title>

    <style type="text/css">
        body, html {
            font-family: sans-serif;
        }
    </style>

    <script src="../../vis.js"></script>
</head>
<body>
<div id="visualization"></div>

<script type="text/javascript">
    var container = document.getElementById('visualization');
    var items = [
        {id: 1, content: 'item 1', start: '2013-04-20'},
        {id: 2, content: 'item 2', start: '2013-04-14'},
        {id: 3, content: 'item 3', start: '2013-04-18'},
        {id: 4, content: 'item 4', start: '2013-04-16', end: '2013-04-19'},
        {id: 5, content: 'item 5', start: '2013-04-25'},
        {id: 6, content: 'item 6', start: '2013-04-27'}
    ];
    var options = {};
    var timeline = new vis.Timeline(container, items, options);
</script>
</body>
</html>

Loading

Install or download the vis.js library. in a subfolder of your project. Include the library script in the head of your html code: 

<script type="text/javascript" src="vis/vis.js"></script>
The constructor of the Timeline is vis.Timeline 
var timeline = new vis.Timeline(container, items, options);
The constructor accepts three parameters:

Data Format

The Timeline uses regular Arrays and Objects as data format. Data items can contain the properties start, end (optional), content, group (optional), and className (optional).

A table is constructed as: 

var items = [
    {
        start: new Date(2010, 7, 15),
        end: new Date(2010, 8, 2),  // end is optional
        content: 'Trajectory A'
        // Optional: a field 'group'
        // Optional: a field 'className'
        // Optional: a field 'editable'
    }
    // more items...
]);

Properties

The item properties are defined as:

Name Type Required Description
start Date yes The start date of the item, for example new Date(2010,09,23).
end Date no The end date of the item. The end date is optional, and can be left null. If end date is provided, the item is displayed as a range. If not, the item is displayed as a box.
content String yes The contents of the item. This can be plain text or html code.
type String 'box' The type of the item. Can be 'box' (default), 'range', or 'point'.
group any type no This field is optional. When the group column is provided, all items with the same group are placed on one line. A vertical axis is displayed showing the groups. Grouping items can be useful for example when showing availability of multiple people, rooms, or other resources next to each other.
className String no This field is optional. A className can be used to give items and individual css style. For example, when an item has className 'red', one can define a css style .red { background-color: red; border-color: dark-red; } . More details on how to style items can be found in the section Styles.

Configuration Options

Options can be used to customize the timeline. Options are defined as a JSON object. All options are optional. 

var options = {
    width: '100%',
    height: '30px'
};

The following options are available.

Name Type Default Description
align String "center" Alignment of items with type 'box'. Available values are 'center' (default), 'left', or 'right').
autoResize boolean false If true, the Timeline will automatically detect when its container is resized, and redraw itself accordingly.
end Date none The initial end date for the axis of the timeline. If not provided, the latest date present in the items set is taken as end date.
height String none The height of the timeline in pixels or as a percentage. When height is undefined or null, the height of the timeline is automatically adjusted to fit the contents. It is possible to set a maximum height using option maxHeight to prevent the timeline from getting too high in case of automatically calculated height.
margin.axis Number 20 The minimal margin in pixels between items and the time axis.
margin.item Number 10 The minimal margin in pixels between items.
max Date none Set a maximum Date for the visible range. It will not be possible to move beyond this maximum.
maxHeight Number none Specifies a maximum height for the Timeline in pixels.
min Date none Set a minimum Date for the visible range. It will not be possible to move beyond this minimum.
order function none Provide a custom sort function to order the items. The order of the items is determining the way they are stacked. The function order is called with two parameters, both of type `vis.components.items.Item`.
orientation String 'bottom' Orientation of the timeline: 'top' or 'bottom' (default). If orientation is 'bottom', the time axis is drawn at the bottom, and if 'top', the axis is drawn on top.
padding Number 5 The padding of items, needed to correctly calculate the size of item ranges. Must correspond with the css of item ranges.
showMajorLabels boolean true By default, the timeline shows both minor and major date labels on the time axis. For example the minor labels show minutes and the major labels show hours. When showMajorLabels is false, no major labels are shown.
showMinorLabels boolean true By default, the timeline shows both minor and major date labels on the time axis. For example the minor labels show minutes and the major labels show hours. When showMinorLabels is false, no minor labels are shown. When both showMajorLabels and showMinorLabels are false, no horizontal axis will be visible.
start Date none The initial start date for the axis of the timeline. If not provided, the earliest date present in the events is taken as start date.
type String 'box' Specifies the type for the timeline items. Choose from 'dot' or 'point'. Note that individual items can override this global type.
width String '100%' The width of the timeline in pixels or as a percentage.
zoomMax Number 315360000000000 Set a maximum zoom interval for the visible range in milliseconds. It will not be possible to zoom out further than this maximum. Default value equals about 10000 years.
zoomMin Number 10 Set a minimum zoom interval for the visible range in milliseconds. It will not be possible to zoom in further than this minimum.

Methods

The Timeline supports the following methods.

Method Return Type Description
setGroups(groups) none Set a data set with groups for the Timeline. groups can be an Array with Objects, a DataSet, or a DataView.
setItems(items) none Set a data set with items for the Timeline. items can be an Array with Objects, a DataSet, or a DataView.
setOptions(options) none Set or update options. It is possible to change any option of the timeline at any time. You can for example switch orientation on the fly.

Styles

All parts of the Timeline have a class name and a default css style. The styles can be overwritten, which enables full customization of the layout of the Timeline.

For example, to change the border and background color of all items, include the following code inside the head of your html code or in a separate stylesheet.

<style>
    .graph .item {
      border-color: orange;
      background-color: yellow;
    }
</style>

Data Policy

All code and data are processed and rendered in the browser. No data is sent to any server.