Open-source project
NUKnightLab/TimelineJS3 avatar
NUKnightLab/TimelineJS3

TimelineJS3: Knight Lab's Storytelling Timeline for the Web

TimelineJS v3: A Storytelling Timeline built in JavaScript. http://timeline.knightlab.com

3,236 stars643 forksJavaScriptMPL-2.0

At a glance

What is it?
TimelineJS3 is a JavaScript library that renders a scrollable, media-rich timeline from a Google Sheet or a JSON file. It is built for non-programmers first, with a JavaScript API that the project itself describes as only roughly documented.
Who is it for?
Adopt TimelineJS3 when the author is a journalist, historian or communications person who needs a media-rich timeline without writing a renderer, and when the embed route is acceptable. Skip it when the timeline is one component inside a larger React or Svelte application, because the API is documented as not thoroughly tested outside the iframe model.
Can I use it commercially?
Yes, with conditions. MPL-2.0 is a weak copyleft licence: you can use it inside commercial and closed-source software, but if you distribute changes to its own files, you must publish those changes under the same licence.
Is it still maintained?
Yes. The repository last received commits 54 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • NUKnightLab/TimelineJS33,236 ★ · +15
Star history
Repository2026-09-242026-11-15
NUKnightLab/TimelineJS33.2k3.2k

15 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What TimelineJS3 solves, and who it is actually for

Most timeline libraries assume the person building the timeline is a programmer. TimelineJS3 assumes the opposite. The README states that it is "a tool designed to help people with minimal technical skill tell rich, dynamic stories on the web," and the whole product is arranged around that premise. The typical path is not npm install at all. A user opens the authoring tool at timeline.knightlab.com, fills in a Google Sheet whose columns define dates, headlines, text and media, and then pastes an HTML snippet into a page. The library reads the published sheet and renders the timeline inside an iframe.

That decision shapes everything downstream. Because the primary artifact is an embed, the JavaScript API is secondary. The README is blunt about this: the API page "roughly documents TimelineJS's JavaScript API, but note that because TimelineJS's primary use case is the embedded iframe, some of these methods have not been thoroughly tested." For a newsroom, a classroom or a museum communications team, that is a reasonable trade. For a product engineer who wants a timeline component inside a single-page application, it is a warning sign worth reading twice.

The audience is therefore narrow and clear: journalists, educators, archivists and communications staff who have content and a deadline, not a front-end framework. The repository also lists plugins for WordPress, MediaWiki and Drupal, which tells you where the project expects to be embedded in practice.

How the data flows: Google Sheets, JSON, and an iframe

The mechanism is a two-stage pipeline. Stage one is content: either a Google Sheet published to the web, or a JSON file in the format documented at timeline.knightlab.com/docs/json-format.html. Stage two is rendering: the library fetches that source, parses it into a timeline data structure, and paints a horizontal, scrollable timeline with a date axis, slide panels and media.

The repository layout reflects this split. The source lives in src/, the build is produced by vite build followed by node tasks/compile_less.js, and the runtime dependencies are only dompurify and wicg-inert. That dependency list is informative. DOMPurify is present because timeline content frequently comes from a spreadsheet that many people can edit, so untrusted HTML has to be scrubbed before it reaches the DOM. wicg-inert is there to manage focus and interaction on off-screen slides, which is the kind of detail that matters when a timeline holds dozens of panels.

The CSS is shipped separately and imported by the consumer. Media handling is broad rather than deep: the media-types documentation lists which sources are supported, and that page is the one the README recommends "to users of any technical level." If your asset is not on that list, the library will not invent a renderer for it.

Installing TimelineJS3 from npm and rendering a first timeline

The README gives one install path for developers: ES6 modules with a bundler. Import the Timeline class and the stylesheet from the @knight-lab/timelinejs package. Note that the CSS is a separate import; skipping it produces an unstyled timeline.

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

With those two imports in place, you need a container element in the page and a data source. The library accepts either a URL to a published Google Sheet or a URL to a JSON file in the documented format. The README does not print a full constructor example on the repository page, so the exact option keys belong to the configuration page at timeline.knightlab.com/docs/options.html rather than to this article. Treat that page as the reference before you write the call.

For working on the library itself, the package scripts are the entry point. The build is two steps, and the dev server is Vite.

bash
npm install
npm run build
npm start

npm run build runs vite build and then node tasks/compile_less.js, which compiles the Less stylesheets into CSS. npm start launches the Vite dev server. There is also npm run disttest, which builds and then opens http-server at /embed/index.html with debug=true, language=es and an empty script_path query parameter. That URL is the fastest way to see whether a change to the source actually altered the rendered output.

The iframe is the product, and the API is the compromise

The most important limitation is stated by the project itself. Because TimelineJS3 is designed around the embedded iframe, the JavaScript API has not been thoroughly tested for every method. If you instantiate a timeline directly in a page and then try to drive it programmatically, you are working in the part of the codebase the maintainers describe as roughly documented.

There are practical consequences. Styling is scoped to the library's own CSS, so overriding the look means competing with the compiled Less output rather than passing a theme object. The data model is optimized for a linear narrative with dated events; a timeline that needs branching, nested tracks or a non-chronological layout is outside what the format expresses. And because the common path depends on a published Google Sheet, the content pipeline inherits Google's sharing rules. A sheet that stops being published takes the timeline down with it, and the README does not document a fallback for that case.

There is also a dependency question. The package depends on DOMPurify and wicg-inert, and the package.json pins a set of transitive versions through an overrides block covering brace-expansion, js-yaml, postcss, test-exclude and glob. That block is a maintenance signal: someone has to keep those pins current, and the pins exist because upstream versions were not acceptable.

TimelineJS3 versus building on a charting library

The obvious alternative is a general visualization library such as D3, or a component library in your own framework. The difference is not features, it is who owns the layout. D3 gives you scales, axes and selections; you write the timeline. TimelineJS3 gives you a finished timeline and you supply the content. That trade is the whole decision.

If your timeline needs a custom interaction model, a bespoke visual language, or integration with application state, a charting library will cost more up front and less later. If your timeline needs to look like a TimelineJS timeline and be authored by someone who does not write JavaScript, the library wins immediately, because the authoring tool and the Google Sheets format are the actual product. The README's own framing supports this: general users are pointed to timeline.knightlab.com, and the GitHub repository is described as "primarily directed at those who are interested in working with the TimelineJS source code."

One more distinction matters for teams with strict content policies. TimelineJS3 sanitizes incoming HTML with DOMPurify, which means you are not expected to trust the spreadsheet. A hand-rolled renderer that injects sheet content directly into the DOM would need to solve that problem yourself.

Licence, maintenance and the cost of upgrading

TimelineJS3 is licensed under MPL-2.0, the Mozilla Public License 2.0. MPL-2.0 is file-level copyleft: modifications to files that are part of the covered source must be made available under the same licence, while larger works that combine the library with other code can be distributed under different terms. For most embed users this is a non-issue, since they consume the built package without modifying it. Teams that fork src/ and ship the modified files should read the licence text rather than assume. This is not legal advice.

The repository is not archived, and the last push to master was on 2026-09-22. The package version in package.json is 3.9.13. The repository has no published GitHub releases, so the version number in the manifest is the concrete artifact to check.

Upgrade cost is dominated by the build toolchain rather than the runtime API. The devDependencies sit on Vite 8, Jest 30 and Babel 7, and the build is a two-step script that ends in a custom Less compiler. A consumer who only imports the published package is insulated from all of that. A consumer who vendors the source inherits the overrides block and the Less pipeline. The runtime dependencies are only two packages, which keeps the surface small for everyone else.

Editorial conclusion

Adopt TimelineJS3 when the author is a journalist, historian or communications person who needs a media-rich timeline without writing a renderer, and when the embed route is acceptable. Skip it when the timeline is one component inside a larger React or Svelte application, because the API is documented as not thoroughly tested outside the iframe model. Before committing, verify three things: that your content fits the JSON format at timeline.knightlab.com/docs/json-format.html, that your media types are covered by the media-types page, and that the MPL-2.0 file-level copyleft is acceptable to your legal team. The last push to master was on 2026-09-22.

Frequently asked questions

Is TimelineJS free?

The source is published under MPL-2.0, so you can use and modify it at no cost. The README also points general users to the official authoring tool at timeline.knightlab.com, where timelines are created and embedded.

How can I create a timeline in JavaScript with TimelineJS3?

Import the Timeline class and the stylesheet from the @knight-lab/timelinejs package in an ES6 module project, then supply a published Google Sheet or a JSON file in the documented format as the data source. The README notes that because the embedded iframe is the primary use case, some JavaScript API methods have not been thoroughly tested.

What is the best free timeline maker for a TimelineJS3-style timeline?

TimelineJS3 itself is free and open source, and the README describes it as a tool for people with minimal technical skill to tell stories on the web. It ships plugins for WordPress, MediaWiki and Drupal to simplify embedding, and the authoring tool handles creation for non-programmers.

Official sources

  1. Issues
  2. License: MPL-2.0
  3. NUKnightLab/TimelineJS3 on GitHub
  4. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/nuknightlab-timelinejs3.svg)](https://hysenlabs.com/projects/nuknightlab-timelinejs3)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/nuknightlab-timelinejs3.svg)](https://hysenlabs.com/projects/nuknightlab-timelinejs3)

Was this useful?