Creating an Interactive Timeline with TimelineJS

Written By: Greg Lord

This toolkit offers an introduction to the free and open source tool TimelineJS, allowing users to create interactive visual timelines using nothing but a spreadsheet. This toolkit begins with instructions on setting up a new TimelineJS timeline, and includes steps on how to publish your timeline to the web as an embedded feature on any website–including CMS platforms such as WordPress and Omeka S.

1. Introduction and Overview

TimelineJS is a simple tool for creating interactive timelines without the need for coding or web design. It is a free and open source tool created by Knight Lab, Northwestern University.

TimelineJS generates the interactive timeline features automatically from a metadata spreadsheet template, which can then be updated in real time and made available by embedding it into any existing website (similar to “embedding” a YouTube video player on a site).

The interactive interface supports a wide range of interactive media such as images, audio, and video, and has built-in support for embedding media from other multimedia platforms such as YouTube for videos, SoundCloud for audio, etc.

Finally, TimelineJS is ideally suited for collaborative workflow, as the only tool required for editing content is a Google Sheets spreadsheet, which can inherently be shared among as many authors as required. Once a TimelineJS spreadsheet is edited, the changes to that spreadsheet are automatically reflected by the online TimelineJS tool, and your interactive timeline will update in real time.

2. Setting up a new TimelineJS

Creating a TimelineJS timeline does not require installing any software installation or tools other than the use of any Google account. This account can be any kind of Google account, including free public accounts and/or academic accounts, etc.

To get started, first log into any Google Account you wish to use.

From there, you can navigate to the TimelineJS website and scroll down to the “Make a Timeline” section to begin following the setup instructions.

In Step 1, you can click the “Get the Spreadsheet Template” button to begin to setup your TimelineJS spreadsheet.

The link will open up a new browser tab that prompts you to create an editable copy of Knight Lab’s “Official TimelineJS3 Template” file. Click the “Make a copy” button and you will be taken to a new Google Sheets document.

This file serves as an example spreadsheet including prefilled data that you can begin by modifying, to experiment with the data. It includes one “title” slide and two content slides.

This is a good time to rename your document to something meaningful, particularly if you will be sharing this document with other collaborators. You can do this by clicking on the title to edit it (or by going to File > Rename).

This file will serve as the metadata for your project, but it is not yet usable by TimelineJS. To make it accessible on the web, we will follow Step 2 on the TimelineJS page as follows:

Under the “File” menu, hover over the “Share” menu item, and then choose “Publish to web” in the submenu that opens.

You will see a popup window that prompts you to publish your spreadsheet. Click the green “Publish” button to make this spreadsheet readable by the TimelineJS web tool. (Important note: this does not mean that your spreadsheet is editable by other Google accounts. It is just making the data in this sheet available (as read only) by the TimelineJS web tool. You can, of course, still make your sheet editable by other users in the usual manner, by clicking “Share” in the upper right of the Google Sheets editor.)

Once you have clicked “Publish” you can ignore the URL that will appear in the next confirmation window. Close this popup and then, instead, copy the main URL of your Google Sheets window. We will provide TimelineJS with this address in the next step.

Finally, on the main TimelineJS website page, scroll to Step 3 (Generate your timeline) and paste the URL you copied in the previous step into the “Google Spreadsheet URL” box. You can leave the “Width” and “Height” options at their default values for now.

Once you have pasted this link, you will see the text boxes below update automatically, in the fields beside Step 4 (Share your timeline).

You can preview your timeline by clicking the “Open Preview in a new window” button. This will be helpful for beginning to edit and customize your timeline. Ultimately we will be publishing this timeline to a website, however, by using the Embed code generated in the block above. This code (much like a YouTube video player embed code) will let the TimelineJS tool generate a block on any website we add this code to, essentially displaying our TimelineJS timeline as a small section of its own website within our own. (We will cover this in an upcoming step!)

For now click “Open Preview in a new window” to begin to test your timeline!

3. TimelineJS Title Slide

When you open your TimelineJS preview in a new window, you will see the TimelineJS interface presented in a blank window. This is a chance to see how TimelineJS makes use of each of the fields in its Google Sheets template.

If you switch between your Google Sheets spreadsheet and your TimelineJS preview, you will be able to see each of the fields in the template file displayed in the TimelineJS interface. The screenshot below highlights each element of the interface as it relates to the first row of the template spreadsheet (row 2).

The main interface of TimelineJS arranges each of these fields in this same manner, where “Headline” and “Text” comprise the main body of a timeline “slide,” and supporting elements such as “Media” (and “Media Caption” and “Media Credit”) provide a visual to accompany the content.

This first row is unique in that is a “title” slide (see the dropdown value currently set to “title” in Column P), which means that it serves as the default first slide someone will see when they arrive at this timeline.

Other slides will all contain chronological data, which will arrange them along the horizontal timeline below. We’ll cover that next!

4. TimelineJS Timeline Slides

The bottom section of the TimelineJS interface is the interactive timeline itself. This is arranged as a horizontal row of individual “slides” that are arranged chronologically from the oldest to the newest dates present in the Google Spreadsheet.

The range and granularity of units represented by the timeline view are created automatically by the type of data you create, where, in this example, the timeline is as specific as individual days. (For example, this could be as wide as large ranges of years for a timeline project that covers a wider range of time.)

Each entry in the spreadsheet is added automatically as a small clickable block that includes that entry’s “Headline” field as a label.

You can control this timeline view in a number of ways:

  • The timeline can be scrolled freely by clicking and dragging on any blank background area of the timeline
  • Clicking any timeline block will automatically advance to that slide
  • Clicking the Zoom In/Out buttons on the left will adjust the chronological scale of the timeline view
  • Clicking Next or Previous slides (on the left, or shown above to the right of the current slide in the main area) will advance/reverse through adjacent slides

Clicking on the next slide shows the standard interface for a content slide, which you can again compare to the data provided by the template spreadsheet:

As before, the main content area is provided by the “Headline” and “Text” fields, although in main content slides such as these, both the position in the timeline and the date labels above the Headline are provided by the two sets of “Year/Month/Day/Time” fields in the spreadsheet. The first set of these (columns A-D, labeled in red backgrounds on the spreadsheet template) are the primary fields that are used to position this slide in the timeline. The optional “End Year/Month/Day/Time” fields (columns E-H) provide an end date for this slide, if we are describing something that had both a beginning and end date.

Importantly, we can also override this field by supplying a “Display Date” (column I) which will display whatever text we prefer. This can be useful in instances where dates are vague, perhaps where we might prefer the label to say things such as “Summer 2024” or “Circa 1200 A.D.”, etc., than any particular date. In that case, we can (and should) still use columns A-D to provide a specific date so that it falls in a useful place on our timeline, but this allows a less specific label to communicate the uncertain dates.

All other content slides in a typical TimelineJS will behave this same way. We can add as many slides as we like, and they will arrange themselves into a timeline as long as we need to accommodate all of the dates and entries listed.

In the example below, taken from the Reckonings community partner project “Asian American Media Activism in Boston“, we can see that when multiple slides fall on the same date, or overlapping date ranges, the slides will stack vertically along the timeline view to make room for one another.

5. Publishing our TimelineJS Timeline

When you are ready to publish your TimelineJS to the web, you can return to the TimelineJS website where the “Embed” field in Step 4 of their instructions (see section above) provides the “embed code” that we will need to add this TimelineJS block to the code of our website. (This is specifically the second block under their Step 4, which should begin with the “<iframe>” tag.)

As an example, we will cover adding this to an Omeka S website. For more information about how to setup Omeka S, or create Omeka S pages such as the one below, please visit our “Building an Archive with Omeka S” toolkit.)

Please note that this process is ultimately applicable to any website. We are essentially just adding this embed code as an “iframe” tag to whatever website we choose, as a block of HTML.

Within Omeka S, we can add our TimelineJS block to any Page we like. As an example, we will create a new Page and add the HTML block that will house our TimelineJS embed code.

First, log in to Omeka S, and navigate to a Site where you have authorship permissions. With your Omeka S Site selected, click the Pages menu in the sites menu to the left of the Omeka S dashboard. From there, we can either edit an existing page or click “Add new page” in the upper right.

If you are creating a new page, give your page a Title,  URL Slug, and (optionally) add the page to your site’s navigation as normal.

Once you are in the Page editor screen, add a new HTML block from the “Add new block” menu on the right. This will add a new empty “HTML” block to your main content area. We will use this as the place to post our TimelineJS in the next step.

When you click into the HTML block’s text field, a new menu will appear above the text editor with a number of editing buttons. Click on the one in the upper left called “Source.”

When you click this button, the Source Code editor opens up. This is essentially an HTML editor window, letting us supply whatever content we would like in HTML format. We will use this as the place to insert our TimelineJS embed code, as that code is a block of HTML text (an iframe). In the window that opens, paste your TimelineJS embed code and click “OK” at the bottom.

You should now see a small preview of your TimelineJS code in the HTML block, which is generated automatically by the TImelineJS service.

From here, we can either click “View” to preview our page and TimelineJS block, or “Save” to publish this page to the web.

Once your page is saved, your TimelineJS will be publicly viewable on the website!

6. Updating your TimelineJS Timeline

As a final note, the TimelineJS service is automatically updated each time a user loads your Timeline (or any website upon which you have embedded your Timeline). This is thanks to the earlier step of having published our Google Sheet to the web.

Because of this, any updates you make to your Google Sheet will automatically be saved and published, meaning that the Timeline will automatically see and include these changes the next time it is loaded. Importantly, this will not require any changes to your Omeka S page (or wherever else you have published it) itself!