Introduction to TimelineJS

TimelineJS allows you to create a visually attractive timeline that may incorporate a variety of media. Created by the Knight Lab at Northwestern University, the tool is primarily intended for journalists but can be used in many disciplines and is particularly useful for digital humanities projects.

The code of TimelineJS is open source and hosted on GitHub, but most users will find the Web-based tool offered by the Knight Lab as the easiest approach.

Getting Started

The first step is to get familiar what TimelineJS can do for you. The TimelineJS home page is very well-written and should be your first source of information for learning about this tool. Examples showcase the types of projects that can be developed with TimelineJS. Some good examples include

The second step is to think about what you want to accomplish with TimelineJS. Remember that TimelineJS is created by and for journalists. That means it aims to present a story about an event in current or recent history. Of course, the purpose of any timeline is to visually convey information. TimelineJS does that through combining the timeline feature with the options of media, audio, video, and nicely formatted text.

The third step is to gather your data. This is the most time-consuming part of the process and, possibly, the most difficult depending upon your project. You may choose to gather the data in whatever way works best for your project, but it ultimately will need to go into some type of spreadsheet. The Knight Lab provides a Google Spreadsheet template available from the TimelineJS home page.

Before diving into the spreadsheet you may want to prepare a storyboard for your timeline. While you can do this via the spreadsheet, doing so prior on paper or other form can help organize your thoughts and the story you’re telling through the data without the distraction of the spreadsheet and the software. Later, once you have all your data organized then you can more easily see how it fits together through the TimelineJS Google Spreadsheet.

 Editing the TimelineJS Google Spreadsheet

One of the more confusing aspects of TimelineJS is understanding how the seven fields in the provided spreadsheet map to what is displayed on the timeline even though the spreadsheet template does provide sample data and description within the file.

TimelineJS elements

Only two fields in the spreadsheet are required: start Date, headline. You often will use the media and text fields, also. Be sure to use the media credit field if you’re not using your own material. The media thumbnail field is less useful. The type field is primarily to indicate which entry should be the the title slide. (There’s also an option for era to indicate a span of dates.) Slides also can be categorized with the tag field.)

Important: do not change the first row of the spreadsheet. The fields must stay in the same order for TimelineJS to process the data.

Text fields are HTML, so you can include a link for more information.

Dates are an essential part of any timeline. TimelineJS can handle dates as precise as minutes and seconds if you project calls for a detailed scenario of events. Other projects may need to indicate only days, spans of days, a particular month, a span of months, a specific year, or a span of years. Unless you are working with current events, you will want to format the start date and end date fields as plain text. This will allow you to enter the following types of dates without a problem. In Google spreadsheet: select the column (either start date or end date) then click “Format > Number > Plain Text”.

To enter a single day (e.g., January 1, 1525): enter “01/01/1525” in the start date.
To enter a span of days (e.g., June 20 – 25, 1550): enter “06/20/1525” in the start date. and “06/25/1550” in the end date.
To enter a single month (e.g., July 1575): enter “07/1575” in the start date.
To enter a span of months (e.g., January 1605 – June 1505): enter “01/1605” in the start date and “06/1605” in the end date.
To enter a specific year (e.g., 1500): enter “1500” in the start date.
To enter a span of years (e.g., 1485-1603): enter “1485” in the start date and “1603” in the end date.

Here is a sample of a timeline created with the display of various dates and other fields. Note that the width of the web page will impact the display format of the timeline. This can be particularly problematic when displaying a timeline within certain WordPress themes that have narrow widths:

The type field allows for entry to represent an era, which will color code the entire section in the timeline that covers those dates.

 Publishing your timeline

The TimelineJS home page has clear directions for generating and previewing the timeline, but some users may be lost as to how to embed the timeline on their website. Yes, you need a website in order to display your timeline. The timeline exists as an iframe and can easily be embedded in any website, e.g., WordPress.

Additional sources to learn more about TimelineJS

Here’s another example of using TimelineJS:

TimelineJS at W&L

An excellent example of the use of TimelineJS is the British Reformation in Context, which was done by the students in History 229-02: Blood, Sex, and Sermons: The History of the Reformation in Britain, which was taught in Winter term 2015 by Professor Michelle Brock.

For futher information If you’re W&L faculty or students, contact the Digital Humanities Action Team for assistance in using TimelineJS by sending email to