Customized timeline with Timeline.js

When we discussed the redesign of our website in the fall of 2013 we wanted the new site not only to reflect our company as it is now but also pay tribute to the fact that Boyle Software has been around for over 25 years. In the IT world that is a fairly long time.

Note: This post refers to an old version of TimelineJS with a now outdated file structure. Please use the latest version:

We looked at different ways to represent history on a web page. Timeline.js quickly became our favorite. And it is very easy to implement if you follow the 4-step instructions on their site.

However, in our case we wanted to eliminate the dependency on an external spreadsheet and use JSON instead of a Google Doc. That way we would be able to host the entire timeline on our own server and have full control over it.

Step 1: Get the Timeline.js project from Github

Go to and clone/download the project. All the files that are needed to create your self-hosted version of Timeline.js are in the /build and /examples folders.

Step 2: Basic file structure

Final file structure of customized Timeline.js
I created a /timeline folder in the root directory of our server and copied over the folders/files from the /build folder of the Timeline.js project. I left the /css directory as is (including the .png files) and only removed the /themes folder since I was fine with the elegant default layout of the timeline. The content of /timeline can be seen in the graphic to the left.

The index.html file contains the actual timeline. I wanted the entire timeline to sit in its own directory and then display it within an iframe on whichever page it was supposed to go. The content of index.html is very simple. Using a .jsonp file as the data source our new timeline was quickly populated with events.

This is what index.html looks like:

You can find a template for your .jsonp file in the /example folder of the Timeline.js project downloaded from Github.

Step 3: Embed your timeline

Once you added your own data to the .jsonp file, embed your timeline like this:

Just make sure that you replace the path to the timeline index file with the path on your server and modify the dimensions according to your needs.

That’s all there is to it. Since you are in control of the CSS you can modify the appearance of your timeline as much as you like. You can see our timeline here.

About Uwe Kristen

After graduating in Scottish Literature at University of Glasgow in 1996 Uwe put down his empty glass and left the pub. He took the next airplane to New York City and started coding websites. He still codes. He still reads.

15 thoughts on “Customized timeline with Timeline.js

  1. I’ve been fiddling around with timeline.js and got lost within it for a time. Thanks for the clear info.

  2. By “button” do you mean the arrows? I don’t see any other buttons in the example you provided. The arrows are the timeline defaults, just as the labels in the event line at the bottom.

  3. Yes i did mean the arrows.

    I am trying to do a custom implementation of timeline.js and cant seem to figure out how to enable this feature.

    Do i have to enable these in the timeline options?


  4. Hi,

    There’s also another cloud-based timeline service that was just introduced by Lifestreams Technologies. It lets content providers and developers integrate dynamic, interactive, multimedia activity streams into any website or app, without any reliance on a particular social network or online data source. You can check it out and apply for early access to the technology at

  5. Would be nice to have a tiny example of how the jsonp file should look like.
    The default file looks like:
    storyjs_jsonp_data = {

    Q: In my test, it should look like:
    storyjs_jsonp_data = {
    …. correct???

  6. You can rename it, but there is no need to. I would not recommend it, especially since the timeline container itself also has the ID “timeline-embed”. I would stick with the default.

  7. Guess I’m the only one who could not figure out how to implement this :/ Searched the web for “step by step” tutorial, but did not find anything…

  8. I’m searching for it but can’t find a clear answer.
    1- where do I need to put the timeline.js file in my website root folder?
    2-wich of the index.html do I have to use?
    3-how can I link my iframe with my timeline?

    please need your help.

  9. excuse me for my noob question but when you explained this:

    “Go to and clone/download the project. All the files that are needed to create your self-hosted version of Timeline.js are in the /build and /examples folders.”

    I tried to follow by downloading the zip file and extracting it…but while I can see /examples folder I do not get a /build folder which seems to be essential for taking the next steps in self-hosting…i.e., I don’t have the timeline.css or index.html files in /examples.

    what did I not do right?

  10. Till Krueger is correct: the latest release of TimelineJS does not contain a /build folder in the downloadable archive.

    The older releases of TimelineJS have these subfolders off the root of the ZIP archive: Build, Examples, Source, Tests, Website.

    The current release of Timeline JS containts these subfolders off the root: Examples, Source, Tests, Website.

    Could you possibly add a note to your excellent steps here as to what folders/files from the current TimelineJS archive need to be uploaded to the server?

    Thank you!

Comments are closed.