Skip to main content
Aonghus Storey


Timeline.js is a small JavaScript module for drawing a timeline diagram using SVG. It provides a way to represent the interactions, merges, splits, appearance, and disappearance of elements over time. Those elements could represent media, software projects, organisations, and so on. Events can be added on the timeline and on particular entries to mark interesting points.

For example, the timeline below represents how Linux desktop environments have developed since the mid-1990s.

A timeline of Linux Desktop Environments. (Not an exhaustive list).

Key features

  • Draw connections between entries with SVG, based on provided attributes
  • Add expandable event markers to the timeline – either along the date-line or on a specific entry
  • Optional panning and zooming functionality and control buttons (using @panzoom/panzoom)
  • Optional search filters entries by name and pans to and highlights the entry
  • Position all entries automatically, or set some manually for more fine-grained control of the diagram
  • Group entries without a direct connection to position them in the same segment of the timeline

Timeline.js takes a set of entries and uses their defined attributes to determine their position and connections to other entries, which are then drawn with SVG. It can also include a set of events, which will show an expandable information marker, either on the date line or on a specific entry. Both entries and events can be added either using data- attributes, or passed as javascript objects when creating the diagram. The example above is created with the following HTML:


<div id="diagram">
	<!--Timeline entries-->
	<div id="KDE" data-start="1996" data-become="Plasma" data-colour="#179af3">KDE</div>
	<div id="Plasma" data-start="2014" data-colour="#179af3">KDE Plasma</div>
	<div id="Trinity" data-start="2010" data-split="KDE" data-colour="#01306f">Trinity Desktop Environment</div>
	<div id="Budgie" data-start="2014" data-split="GNOME"  data-colour="#6bca81">Budgie</div>
	<div id="GNOME" data-start="1997"  data-colour="#000">GNOME</div>
	<div id="Cinnamon" data-start="2013" data-split="GNOME" data-colour="#dc682e">Cinnamon</div>
	<div id="MATE" data-start="2011" data-split="GNOME" data-colour="#9ddb60">MATE</div>
	<div id="XFCE" data-start="1997" data-colour="#00a8dd">XFCE</div>
	<div id="LXDE2" data-start="2013" data-split="LXDE" data-irregular="true"  data-colour="#d1d1d1">LXDE</div>
	<div id="LXDE" data-start="2006" data-become="LXQT"  data-colour="#d1d1d1">LXDE</div>
	<div id="LXQT" data-start="2013"  data-colour="#0280b9">LXQT</div>
	<div id="Razor-qt" data-start="2010" data-merge="LXQT"  data-end="2013" data-colour="#006c96">Razor-qt</div>
	<div id="Enlightenment" data-start="1997" data-colour="#fff078">Enlightenment</div>
	<div id="Moksha" data-start="2014" data-split="Enlightenment" data-colour="#5a860a">Moksha Desktop</div>
	<div class="event" data-year="2004"> is founded as a fork of XFree86.</div>
	<div class="event" data-year="2008">The Wayland project was started.</div>
	<div class="event" data-year="2011" data-target="GNOME">Gnome 3.0 was released.</div>
	<div class="event" data-year="2008" data-target="KDE">KDE 4 was released.</div>

The Timeline above is created with this JavaScript:

const t = new Timeline("diagram", { 
	yearStart: 1995,
	panzoom: Panzoom

Note: the panzoom feature requires @panzoom/panzoom to be included. This is not bundled, and defaults to null.

You'll find complete documentation of the entries, events and JavaScript configuration in the README file in the Git repository. Timeline.js is available under the GPLv3 licence.



  • JavaScript
  • SCSS
  • HTML


Javascript module to draw a timeline diagram.

View repository