Journalism in the Public Interest

The ProPublica Nerd Blog

TimelineSetter: A New Way to Display Timelines on the Web


TimelineSetter takes a spreadsheet of events -- or even many series of events -- and generates an easy-to-use timeline.

The timeline is a very useful way to visualize sequences of events, and they’re especially useful to orient readers within the complex investigative stories we do at ProPublica. But they’re not very easy to make. As far as we know, there are no good open source frameworks that web developers can use to generate timelines quickly without losing design flexibility. So we made our own, which is debuting today.

By way of background, our most recent timeline was part of our story on disability discharges last month. We found some interesting parallels between what the Education Department was doing to reform the program and one borrower’s attempt to navigate the bureaucracy over the same five-year period. To visualize these parallel paths, we designed a timeline that showed both series events on one bar, but differentiated by color and space.

The timeline we created isn’t ideal; it was coded by hand so the space between events is not to scale, and impressionistic at best. There’s some cool code that automatically stacks cards on top of each other, but we ended up scrapping a few events just to avoid too many cards piling on top of each other.

Worst of all, the amount of labor that was required to put it together was, as you might imagine, big enough to discourage doing very many timelines like it. So we sought a better, more scalable way to accurately display timelines.

What we came up with is a tool called TimelineSetter. It takes a spreadsheet of events – or even many series of events — and generates an easy-to-use timeline. You can see a TimelineSetter-generated timeline accompanying today’s story by T. Christian Miller on the outcomes for five U.S. soldiers’ after a rocket attack in Iraq.

TimelineSetter shows six color-coded series of events — one for each soldier in the blast and one “default” group for events that included multiple soldiers. Users can toggle displaying each series using checkboxes. above the bar. Unlike our bespoke timeline, TimelineSetter also automatically figures out when events happen relative to each other and automatically places “notches” on the timeline bar at the right location.

It supports zooming, dragging, mouse scrolling, double-click to zoom, navigating using the left/right arrow on your keyboard, and even iPhone/iPad swiping and double-tapping. It also allows arbitrary HTML in each event “card,” so we’ve included photos, slideshows and even video embeds in the timeline. While our site’s template is fixed-width, TimelineSetter’s markup and style is fluid, and will fit into whatever sized container we throw it into.

TimelineSetter is mostly written in JavaScript, with a Ruby component to convert a CSV spreadsheet into a JSON object, and a command line application to bake out the HTML/CSS/JS assets ready to drop into a CMS or Amazon S3. There isn’t a server component at all.

We have some more code generalization and fixes we need to do before it’s ready to open source, but we plan to do so as soon as we can. If you’re interested in working with us on the open source release, email us at

We’d like to thank NYU journalism professor Jay Rosen’s Studio20 class, who helped us think through how timelines provide context and help orient readers in a complex story, as part of their “Build a Better Explainer” project. We’re especially grateful to Chelsea Stark and her fellow students for their work.

Jacquie McNish

March 22, 2011, 1:53 p.m.

this is a great visual approach. On a more basic pragmatic level what are some of the better text/ spreadsheet timeline tools that people are using these days. I find Google docs timelines very clunky.

Excellent tool - very clean.  I look forward to using it in our ongoing investigations when it becomes available.

Clark Baker (LAPD ret)
Principal Investigator

Nice work! I really like a lot of the functionality. I have some constructive suggestions though:

Consider moving the Previous and Next buttons to the left. I find the slideshow functionality the easiest way to engage with timeline, especially since you included keyboard functionality.

I would also like to see a way to highlight pivotal points. For example, I would like to know when the blast occurred in the dissability timeline without having to hunt for it.

Thanks for building an offering the tool as open source. I look forward to seeing the code.

Len De Groot
Knight Digital Media Center

Yes, very nice!

Another point: In your example, you have five colors representing each of the soldiers in the timeline. Next to each guy’s name, you also have a swatch of the matching color. So far, so good. Then you apparently have a sixth color that represents events that affect all five. But that sixth color doesn’t appear along the “swatch” line. This is confusing. It’s also limiting; you can turn off display of any individual soldier’s events, but not display of the group’s events.

Also, is there any way to allow the timelines to be placed one above the other rather than on top of each other? You have a large blank space between the timeline and the bottom of the page, and the individual pictures only take up a small part of that space.

Additionally, when I move my mouse over one of the events in the timeline, the cursor changes to a “change column width” icon (like the one you see at the top of a column in a spreadsheet). But there’s no apparent way to widen or narrow any events by any combination of clicking and dragging that I’ve tried. Maybe this is a feature that hasn’t been fully implemented yet?

Finally, and probably most importantly, it seems that you can only display only one news item at a time. This severely restricts your ability to visualize the span of time between events, or compare descriptions of events, since you have to rely on your memory for the content and the identity of the news items that are not displayed. Naturally, it would be hard to read two items that were close on the page, but this could be counteracted by widening the timeline.

I hope these comments were useful. Thanks again for providing us with this tool! 


Superb!! I work with timelines daily, I write chronologies for a yearbook and a website for a Spanish public body. This new tool seems incredible, very dynamic and functional. It would be great using it to organize and to display my works, when available. Thank you so much for offering it!

Hugo Gallego

Although the code is not yet available, our team looked for obvious security holes in the product.  From first inspection, the tool doesn’t appear to pose much of a security risk.  Since there’s no input, you can’t run an SQL injection or similar attacks.  It is javascript-based, which is safer than ActiveX and the Ruby component is negligible.

They also have nice and tidy HTML source (well constructed with no superfluous web design GUI garbage) which tells us that their web programmer knows what he’s doing.  We also attempted to access their javascript CGI directory and was denied.

There’s more to examine when the code becomes available, but from a quick security scan it looks pretty decent.  It’s possible their web server may have some vulnerabilities, but that’s not something we want to pursue without their written permission.

Well done!

Excellent tool - and not just for journalism. This could be used to visualize any arbitrary events that are logged by a computer - a boot log or a record of emails, for example.

I am eager to play with the source. Thanks for providing it!


Commenting is not available in this section entry.