Timeline documentation

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.

Timeline uses regular HTML DOM to render the timeline and items put on the timeline. This allows for flexible customization using css styling.

Overview
Example
Loading
Data Format
- Items
- Groups
Configuration Options
Methods
Events
Editing Items
Localization
Styles
Data Policy

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="../../dist/vis.js"></script>
  <link href="../../dist/vis.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="visualization"></div>

<script type="text/javascript">
  // DOM element where the Timeline will be attached
  var container = document.getElementById('visualization');

  // Create a DataSet (allows two way data-binding)
  var items = new vis.DataSet([
    {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'}
  ]);

  // Configuration for the Timeline
  var options = {};

  // Create a Timeline
  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 libraries script and css files in the head of your html code:

<script src="vis/dist/vis.js"></script>
<link href="vis/dist/vis.css" rel="stylesheet" type="text/css" />

The constructor of the Timeline is vis.Timeline

var timeline = new vis.Timeline(container, items, options);

The constructor accepts three parameters:

container is the DOM element in which to create the timeline.
items is an Array containing items. The properties of an item are described in section Data Format.
options is an optional Object containing a name-value map with options. Options can also be set using the method setOptions.

Data Format

The timeline can be provided with two types of data:

Items containing a set of items to be displayed in time.
Groups containing a set of groups used to group items together.

Items

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: fields 'id', 'type', 'group', 'className'
  }
  // more items...
]);

The item properties are defined as:

Name	Type	Required	Description
className	String	no	This field is optional. A className can be used to give items an individual css style. For example, when an item has className 'red', one can define a css style like: .vis.timeline .red { color: white; background-color: red; border-color: darkred; } More details on how to style items can be found in the section Styles.
content	String	yes	The contents of the item. This can be plain text or html code.
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.
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.
id	String \| Number	no	An id for the item. Using an id is not required but highly recommended. An id is needed when dynamically adding, updating, and removing items in a DataSet.
start	Date	yes	The start date of the item, for example `new Date(2010,9,23)`.
title	String	none	Add a title for the item, displayed when holding the mouse on the item. The title can only contain plain text.
type	String	'box'	The type of the item. Can be 'box' (default), 'point', or 'range'. Types 'box' and 'point' need a start date, and type 'range' needs both a start and end date.

Groups

Like the items, groups are regular JavaScript Arrays and Objects. Using groups, items can be grouped together. Items are filtered per group, and displayed as Group items can contain the properties id, content, and className (optional).

Groups can be applied to a timeline using the method setGroups. A table with groups can be created like:

var groups = [
  {
    id: 1,
    content: 'Group 1'
    // Optional: a field 'className'
  }
  // more groups...
]);

Groups can have the following properties:

Name	Type	Required	Description
className	String	no	This field is optional. A className can be used to give groups an individual css style. For example, when a group has className 'red', one can define a css style `.red { color: red; }`. More details on how to style groups can be found in the section Styles.
content	String	yes	The contents of the group. This can be plain text or html code.
id	String \| Number	yes	An id for the group. The group will display all items having a property `group` which matches the `id` of the group.
title	String	none	A title for the group, displayed when holding the mouse the groups label. The title can only contain plain text.

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',
  margin: {
    item: 20
  }
};

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	true	If true, the Timeline will automatically detect when its container is resized, and redraw itself accordingly. If false, the Timeline can be forced to repaint after its container has been resized using the function `redraw()`.
clickToUse	boolean	false	When a Timeline is configured to be `clickToUse`, it will react to mouse and touch events only when active. When active, a blue shadow border is displayed around the Timeline. The Timeline is set active by clicking on it, and is changed to inactive again by clicking outside the Timeline or by pressing the ESC key.
editable	Boolean \| Object	false	If true, the items in the timeline can be manipulated. Only applicable when option `selectable` is `true`. See also the callbacks `onAdd`, `onUpdate`, `onMove`, and `onRemove`. When `editable` is an object, one can enable or disable individual manipulation actions. See section Editing Items for a detailed explanation.
editable.add	Boolean	false	If true, new items can be created by double tapping an empty space in the Timeline. See section Editing Items for a detailed explanation.
editable.remove	Boolean	false	If true, items can be deleted by first selecting them, and then clicking the delete button on the top right of the item. See section Editing Items for a detailed explanation.
editable.updateGroup	Boolean	false	If true, items can be dragged from one group to another. Only applicable when the Timeline has groups. See section Editing Items for a detailed explanation.
editable.updateTime	Boolean	false	If true, items can be dragged to another moment in time. See section Editing Items for a detailed explanation.
end	Date \| Number \| String	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.
groupOrder	String \| Function	none	Order the groups by a field name or custom sort function. By default, groups are not ordered.
height	Number \| 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.
locale	String	none	Select a locale for the Timeline. See section Localization for more information.
locales	Object	none	A map with i18n locales. See section Localization for more information.
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 in both horizontal and vertical direction.
margin.item.horizontal	Number	10	The minimal horizontal margin in pixels between items.
margin.item.vertical	Number	10	The minimal vertical margin in pixels between items.
max	Date \| Number \| String	none	Set a maximum Date for the visible range. It will not be possible to move beyond this maximum.
maxHeight	Number \| String	none	Specifies the maximum height for the Timeline. Can be a number in pixels or a string like "300px".
min	Date \| Number \| String	none	Set a minimum Date for the visible range. It will not be possible to move beyond this minimum.
minHeight	Number \| String	none	Specifies the minimum height for the Timeline. Can be a number in pixels or a string like "300px".
moveable	Boolean	true	Specifies whether the Timeline can be moved and zoomed by dragging the window. See also option `zoomable`.
onAdd	Function	none	Callback function triggered when an item is about to be added: when the user double taps an empty space in the Timeline. See section Editing Items for more information. Only applicable when both options `selectable` and `editable.add` are set `true`.
onUpdate	Function	none	Callback function triggered when an item is about to be updated, when the user double taps an item in the Timeline. See section Editing Items for more information. Only applicable when both options `selectable` and `editable.updateTime` or `editable.updateGroup` are set `true`.
onMove	Function	none	Callback function triggered when an item has been moved: after the user has dragged the item to an other position. See section Editing Items for more information. Only applicable when both options `selectable` and `editable.updateTime` or `editable.updateGroup` are set `true`.
onRemove	Function	none	Callback function triggered when an item is about to be removed: when the user tapped the delete button on the top right of a selected item. See section Editing Items for more information. Only applicable when both options `selectable` and `editable.remove` are set `true`.
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 items, for example when setting `options.padding=10`, corresponding css is: .vis.timeline .item { padding: 10px; }
selectable	Boolean	true	If true, the items on the timeline can be selected. Multiple items can be selected by long pressing them, or by using ctrl+click or shift+click. The event `select` is fired each time the selection has changed (see section Events).
showCurrentTime	boolean	true	Show a vertical bar at the current time.
showCustomTime	boolean	false	Show a vertical bar displaying a custom time. This line can be dragged by the user. The custom time can be utilized to show a state in the past or in the future. When the custom time bar is dragged by the user, the event `timechange` is fired repeatedly. After the bar is dragged, the event `timechanged` is fired once.
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.
stack	Boolean	true	If true (default), items will be stacked on top of each other such that they do not overlap.
start	Date \| Number \| String	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	none	Specifies the default type for the timeline items. Choose from 'box', 'point', and 'range'. Note that individual items can override this default type. If undefined, the Timeline will auto detect the type from the items data: if a start and end date is available, a 'range' will be created, and else, a 'box' is created.
width	String	'100%'	The width of the timeline in pixels or as a percentage.
zoomable	Boolean	true	Specifies whether the Timeline can be zoomed by pinching or scrolling in the window. Only applicable when option `moveable` is set `true`.
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
clear([what])	none	Clear the Timeline. An object can be passed specifying which sections to clear: items, groups, and/or options. By Default, items, groups and options are cleared, i.e. `what = {items: true, groups: true, options: true}`. Example usage: timeline.clear(); // clear items, groups, and options timeline.clear({options: true}); // clear options only
destroy()	none	Destroy the Timeline. The timeline is removed from memory. all DOM elements and event listeners are cleaned up.
fit()	none	Adjust the visible window such that it fits all items.
getCustomTime()	Date	Retrieve the custom time. Only applicable when the option `showCustomTime` is true.
setCustomTime(time)	none	Adjust the custom time bar. Only applicable when the option `showCustomTime` is true. `time` is a Date object.
getSelection()	Number[]	Get an array with the ids of the currently selected items.
getVisibleItems()	Number[]	Get an array with the ids of the currently visible items.
getWindow()	Object	Get the current visible window. Returns an object with properties `start: Date` and `end: Date`.
on(event, callback)	none	Create an event listener. The callback function is invoked every time the event is triggered. Avialable events: `rangechange`, `rangechanged`, `select`. The callback function is invoked as `callback(properties)`, where `properties` is an object containing event specific properties. See section Events for more information.
off(event, callback)	none	Remove an event listener created before via function `on(event, callback)`. See section Events for more information.
redraw()	none	Force a redraw of the Timeline. Can be useful to manually redraw when option autoResize=false.
setGroups(groups)	none	Set a data set with groups for the Timeline. `groups` can be an Array with Objects, a DataSet, or a DataView. For each of the groups, the items of the timeline are filtered on the property `group`, which must correspond with the id of the group.
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.
setSelection([ids])	none	Select one or multiple items by their id. The currently selected items will be unselected. To unselect all selected items, call `setSelection([])`.
setWindow(start, end)	none	Set the current visible window. The parameters `start` and `end` can be a `Date`, `Number`, or `String`. If the parameter value of `start` or `end` is null, the parameter will be left unchanged.

Events

Timeline fires events when changing the visible window by dragging, when selecting items, and when dragging the custom time bar.

Here an example on how to listen for a select event.

timeline.on('select', function (properties) {
  alert('selected items: ' + properties.nodes);
});

A listener can be removed via the function off:

function onSelect (properties) {
  alert('selected items: ' + properties.nodes);
}

// add event listener
timeline.on('select', onSelect);

// do stuff...

// remove event listener
timeline.off('select', onSelect);

The following events are available.

name	Description	Properties
rangechange	Fired repeatedly when the user is dragging the timeline window.	`start` (Number): timestamp of the current start of the window. `end` (Number): timestamp of the current end of the window.
rangechanged	Fired once after the user has dragged the timeline window.	`start` (Number): timestamp of the current start of the window. `end` (Number): timestamp of the current end of the window.
select	Fired after the user selects or deselects items by tapping or holding them. When a use taps an already selected item, the select event is fired again. Not fired when the method `setSelection`is executed.	`items`: an array with the ids of the selected items
timechange	Fired repeatedly when the user is dragging the custom time bar. Only available when the custom time bar is enabled.	`time` (Date): the current time.
timechanged	Fired once after the user has dragged the custom time bar. Only available when the custom time bar is enabled.	`time` (Date): the current time.

Editing Items

When the Timeline is configured to be editable (both options selectable and editable are true), the user can move items by dragging them, can create a new item by double tapping on an empty space, can update an item by double tapping it, and can delete a selected item by clicking the delete button on the top right.

Option editable accepts a boolean or an object. When editable is a boolean, all manipulation actions will be either enabled or disabled. When editable is an object, one can enable individual manipulation actions:

// enable or disable all manipulation actions
var options = {
  editable: true       // true or false
};

// enable or disable individual manipulation actions
var options = {
  editable: {
    add: true,         // add new items by double tapping
    updateTime: true,  // drag items horizontally
    updateGroup: true, // drag items from one group to another
    remove: true       // delete an item by tapping the delete button top right
  }
};

One can specify callback functions to validate changes made by the user. There are a number of callback functions for this purpose:

onAdd(item, callback) Fired when a new item is about to be added. If not implemented, the item will be added with default text contents.
onUpdate(item, callback) Fired when an item is about to be updated. This function typically has to show a dialog where the user change the item. If not implemented, nothing happens.
onMove(item, callback) Fired when an item has been moved. If not implemented, the move action will be accepted.
onRemove(item, callback) Fired when an item is about to be deleted. If not implemented, the item will be always removed.

Each of the callbacks is invoked with two arguments:

item: the item being manipulated
callback: a callback function which must be invoked to report back. The callback must be invoked as callback(item | null). Here, item can contain changes to the passed item. Parameter `item` typically contains fields `content`, `start`, and optionally `end`. The type of `start` and `end` is determined by the DataSet type configuration and is `Date` by default. When invoked as callback(null), the action will be cancelled.

Example code:

var options = {
  onUpdate: function (item, callback) {
    item.content = prompt('Edit items text:', item.content);
    if (item.content != null) {
      callback(item); // send back adjusted item
    }
    else {
      callback(null); // cancel updating the item
    }
  }
};

A full example is available here: 08_edit_items.html.

Localization

Timeline can be localized. For localization, Timeline depends largely on the localization of moment.js. Locales are not included in vis.js by default. To enable localization, moment.js must be loaded with locales. Moment.js offers a bundle named "moment-with-locales.min.js" for this and there are various alternative ways to load locales.

To set a locale for the Timeline, specify the option locale:

var options = {
  locale: 'nl'
};

Create a new locale

To load a locale into the Timeline not supported by default, one can add a new locale to the option locales:

var options = {
  locales: {
    // create a new locale (text strings should be replaced with localized strings)
    mylocale: {
      current: 'current',
      time: 'time',
    }
  },

  // use the new locale
  locale: 'mylocale'
};

Available locales

Timeline comes with support for the following locales:

Language	Code
English	`en` `en_EN` `en_US`
Dutch	`nl` `nl_NL` `nl_BE`

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>
  .vis.timeline .item {
    border-color: orange;
    background-color: yellow;
  }
</style>

Data Policy

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