TimelineJS v3: Embeddable Interactive Timelines for Minimal-Code Storytelling

Who TimelineJS v3 Is For and How Most People Use It

TimelineJS v3 is a tool from Northwestern University Knight Lab aimed at people with minimal technical skill who want to publish rich, interactive timelines on the web. The primary workflow involves no JavaScript coding: a user fills in a Google Sheets spreadsheet using the official authoring template, visits timeline.knightlab.com to configure and publish the timeline, and then pastes a generated iframe snippet into their web page or CMS. The README describes this as the main use case and directs general users to the main website for documentation.

Developers with technical requirements have two additional entry points. The first is instantiating a Timeline directly in a page by loading the library from a script tag or npm, rather than using the iframe embed. The second is using the JSON configuration format as a data source instead of Google Sheets, for those who prefer not to couple their content to a Google account. The README notes that the GitHub repository is primarily directed at people working with the TimelineJS source code, not general users.

Google Sheets and JSON as Data Sources

The two supported data backends differ significantly in how content is managed and who manages it. The Google Sheets path is designed for non-technical authors: the official authoring tool at timeline.knightlab.com generates a spreadsheet template, and each row of that spreadsheet represents one event on the timeline. Date, headline, text, and media URL are entered in spreadsheet columns. Updating the timeline later means editing the spreadsheet; the embed reflects changes without modifying any HTML.

The JSON configuration format gives developers full control over the data structure without requiring a Google account. The format is documented at timeline.knightlab.com/docs/json-format.html. Each event entry in the JSON carries date, text, and media fields, mirroring the column structure of the Google Sheets format but expressed as JavaScript objects. Teams that version-control their content alongside source code will prefer JSON because it does not depend on a Google account and can be stored in the repository. The trade-off is that the JSON format requires a developer to read and follow the schema documentation, which the Google Sheets authoring tool handles implicitly.

Embedding TimelineJS and the ES6 Module Path

The iframe embed is the most widely used integration method and requires no JavaScript knowledge. The official authoring tool at timeline.knightlab.com generates the iframe snippet after the data source is configured, and pasting it into a CMS or HTML page is all that is needed.

For projects that use ES6 modules and webpack or similar bundlers, the README documents the npm package import path:

import { Timeline } from '@knight-lab/timelinejs';
import '@knight-lab/timelinejs/dist/css/timeline.css';

This approach lets developers create a Timeline instance directly in a page without an iframe, which is useful when the timeline needs to integrate with surrounding page JavaScript or when the hosting environment restricts iframe use. The README includes a link to a separate API.md file that documents the JavaScript API for this integration path. However, the README also states explicitly that because the iframe embed is the primary use case, some of the API methods documented in API.md have not been thoroughly tested. Developers who rely on those methods should verify the specific calls they need before building a production integration.

CMS Plugins for WordPress, MediaWiki, and Drupal

The README lists plugins for three content management systems that simplify the embedding process. The WordPress plugin is published at wordpress.org/plugins/knight-lab-timelinejs and handles the embed workflow inside the WordPress editor. The MediaWiki extension is documented at mediawiki.org/wiki/Extension:Modern_Timeline. The Drupal integration is documented at drupal.org/docs/8/modules/views-timelinejs.

These plugins are maintained separately from the core TimelineJS repository. The README links to them but does not document their compatibility ranges or maintenance status. An organization running an older version of WordPress or Drupal should check the individual plugin pages for version requirements before installing. The MediaWiki extension is named Modern Timeline, which is worth noting for users searching the MediaWiki extension directory, as the name does not contain "TimelineJS."

What TimelineJS Does Not Do and Where It Falls Short

TimelineJS v3 is a display and navigation tool, not a data management system. It does not store events in a database, provide an admin interface for editing events after the embed is placed, or handle authentication for who can view or modify timeline content. All of that responsibility stays with the data source (Google Sheets or the JSON file the developer hosts).

The JavaScript API, documented in API.md, carries a noted limitation from the README: because the iframe is the primary use case, some methods have not been thoroughly tested. A developer building a custom integration that calls API methods programmatically is working outside the best-supported path. If a method behaves unexpectedly, the gap in test coverage means the bug report may not have an immediate resolution.

The repository has published no GitHub releases. The current version is 3.9.13 per package.json, but there is no GitHub release entry with release notes or downloadable assets. The npm package @knight-lab/timelinejs is the supported distribution channel. The library uses DOMPurify as a runtime dependency to sanitize HTML in timeline content, which is a relevant security measure for installations that allow user-submitted event text.

Comparing with vis-timeline and Maintenance State

vis-timeline is an open-source JavaScript library for rendering interactive timelines with a focus on developer-defined data visualization. Unlike TimelineJS v3, it does not include an authoring tool or Google Sheets integration; all data is defined programmatically in JavaScript objects or arrays. It suits engineering teams building dashboards, project trackers, or data-driven applications where the timeline content is generated by code rather than entered by content authors. TimelineJS v3, by contrast, is built around the assumption that the content author and the technical publisher are different people, and that the content author should not need to touch code at all. Both libraries are free and open source; the distinction is one of intended audience and workflow.

TimelineJS v3's last push to the master branch was recorded on 2026-09-22. The repository is not archived. The MPL-2.0 license allows the library to be used in proprietary applications without requiring that application's source code to be published, provided any modifications to the TimelineJS library files themselves are shared under the same license.

Editorial conclusion

TimelineJS v3 is the right tool for content producers, journalists, and educators who need to publish an embeddable timeline without writing JavaScript. Developers who need programmatic control over timeline data at runtime will find the JavaScript API's incomplete test coverage a constraint worth evaluating. Before using the API-based integration, check the API.md file in the repository and the instantiate-a-timeline documentation, as the README notes that some API methods have not been thoroughly tested due to the iframe embed being the primary use case.

Frequently asked questions

Official sources

1. Issues
2. License: MPL-2.0
3. NUKnightLab/TimelineJS3 on GitHub
4. README