Skip to Main Content

Data Viz Tool: TimelineJS: Home

A guide to creating interactive digital timelines using the Knightlab Foundation's TimelineJS

Introduction to TimelineJS

This tutorial will show you how to create a timeline using the free, open-source tool TimelineJS. An example of a Loyola student TimelineJS charting the history of the New Orleans Opera Association is available on the library website.

If you have any questions as you work through the assignment, please do not hesitate to contact me. You can email me at, or make an appointment to meet with me via phone, video/web conference, or chat.

I'm Elizabeth Kelly and I am the Digital Programs Coordinator in the Monroe Library. I manage the library's digital programs including digital special collections and archives, digital preservation, digital scholarship, scholarly communications, and library web services. I’m also the librarian liaison to Mass Communications, Music Industry, Pop & Commercial Music, Urban and Electronic Music Production, and Digital Film, so if you take classes in those areas, you may see me again or want to reach out to me for research and technology help.

Part of my job is working with students and faculty who are interested in using digital tools in their research, either to help them do their research, or to help them tell the story of their research. In this tutorial I'm going to be working with you on an assignment where you create a collaborative digital timeline with your classmates. 

For this assignment, you’ll be using a tool called TimelineJS which was created by the KnightLab Foundation. TimelineJS is free and open source, which means the code behind it is available for anyone to access and tinker with themself. Open source projects like this are very common in digital scholarship and the digital humanities. TimelineJS and similar programs are also frequently used by journalists to help them tell their stories in a way that’s visually engaging for online readers.

Information is added to the timeline by simply editing a pre-formatted spreadsheet in Google Sheets.* In the following steps, I will show you how to add information to the spreadsheet and populate the timeline.

*Note: your professor will provide you with the URLs for the Google Sheet and its corresponding Timeline

Adding items to your timeline

Following is a step-by-step tutorial on adding items to your timeline.

  1. Open the Google Sheet for your group timeline provided by your instructor.

  2. Note the column headers at the top of the spreadsheet. These tell you what information you can add to your timeline. Do not edit these column headers, delete any columns, or leave any blank rows in your spreadsheet, or your timeline will break. For more information on each column, hover over the column header.
    Google Sheets Column Headers screenshot

  3. TimelineJS automatically reorganizes your spreadsheet entries into chronological order, so it doesn't matter where on the spreadsheet your entry appears; the entries with the earliest dates will appear earliest on the timeline, and the entries with the latest dates will appear latest.

  4. To add a new item, enter a start date. You must enter a year; the other date fields are optional. If your entry spans multiple days, months, or years, you can also enter an end date in columns E-H. If you do not have an end date, leave these blank. Column I, Display Date, allows you to manually enter how you want to display the date, overriding any decisions TimelineJS makes about how to show the date. For example, if the exact date for an event is not known, you could enter estimated date info (ex., 1964) in Columns A-D, but then enter a display date of "Circa 1964."

  5. Next, enter a title and a description for your event in Columns J and K.

  6. Columns L-O are for adding media to illustrate your event. Some examples of websites you can embed media from include Youtube, Vimeo, Wikipedia, and Flickr. See the full list of supported media here. In Column L, paste the link to the media. See how to find the correct link for different types of media here. In Columns M and N, make sure to properly credit your media with the author/creator's name and a caption. Column O allows you to add an optional thumbnail image for your media. Without a thumbnail image, the timeline will display a small icon representing the type of media used. To instead display a thumbnail of your media, enter its URL in Column O.

  7. Skip Column P, "Type." Column P is optional and allows you to categorize your timeline entries in two ways. You can have one title slide that does not have a date and that appears at the beginning of your timeline. The spreadsheet provided by your instructor should already have a Title slide designated with the course number as the title. Your other entries can be categories as "era;" you will not use this designation for this class.

  8. Skip Column Q, "Group." This allows you to group events together and will not be used for this assignment.

  9. Finally, Column R, "Background," is an optional field for customizing the display of your event. You can add a background color to your slide by entering a a CSS hex color value. Or, you can add a background image by entering a URL; as with adding images in Column L, "Media," make sure your URL ends in jpg, gif, png or jpeg.
    TimelineJS Google Sheets Column R screenshot

Troubleshooting your timeline

At any time while you are editing your Google Sheet, you can look at the timeline URL provided by your instructor to see how your event is displaying. There may be lag between when you edit the spreadsheet and when your changes show up on the timeline; be patient, and reload the timeline after a few minutes.

If your event is not displaying the way you want it to, check KnightLab's troubleshooting guides for help; contact me at; or schedule a virtual meeting with me at if it would help to look at your timeline together. Good luck, and I look forward to seeing your finished TimelineJS projects at the end of the semester!


Digital Collections Archivist