JSON Config Files

The easiest way to use Vanilla Timeline is to store and load your data from an external JSON file. This allows you to create many different timelines with different styles that you can easily back up. Just point your timeline at a new JSON file and reload the page to quickly change styles or data. Using progammatic methods, you could generate JSON data dynamically (e.g. from a database) and display it in a timeline. Another advantage of using a JSON configuration file is that your timeline gets initialized automatically. If you use the JSON method, you don't have to add the extra line of Javascript to the bottom of your document to initialize the app. To use an external JSON config file, you just have to add a data attribute named data-json-config to your parent timeline element. Here is an example:

<div class="timeline" data-json-config="/path/to/timeline.json">
  <div class="timeline__wrap">
    <div class="timeline__items">
      ...
    </div>
  </div>
</div>
⚠️ Important Note: if you set a data-json-config value, Vanilla Timeline will prioritize JSON settings and ignore other data attribute values being passed. It's either: inline HTML data attributes or a JSON configuration file — but, not both.

Creating a JSON Config File

We've created a sample JSON file that you can download (or copy/paste), and customize, to create your own .json configuration file. Keep in mind that all fields are not required and you can remove fields you're not using. This sample file contains all the possible fields that are available to the Vanilla Timeline API. You can also compare the JSON options to the inline HTML data attributes and you'll see they're similar. One exception is the "layout mode" setting — data attributes use data-mode and Javascript/JSON use layoutMode instead. Generally, Javascript and JSON use camelCase formatting for option names while data attributes start with prefix "data-" and then use dashes between words.

The lastupdated field uses a specific date format (ISO 8601) and you should adhere to this if you want caching to work properly. Whenever you update node content, you should also update the lastupdated field. This way users with cached content will see the latest changes that you have made. If you type a value in the timelineName field it will appear as a heading above your timeline. The useSwiper option tells Vanilla Timeline that you are using a 3rd party library named SwiperJS which you installed separately to enable touch screen support on horizontal timelines. The default value for this value is false. Certain JSON config options will only have an effect if used in conjunction with other options. For example, the option maxWidth only has an effect when layoutMode is vertical. In horizontal mode, this setting is ignored. Some settings, like rtlMode (right-to-left mode) will override other settings, like startIndex. Any options you don't explicitly set will use default values.

Note: if you load your data via a JSON configuration file you do not have to initialize the app with a separate block of Javascript code! After the JSON data is loaded, Vanilla Timeline initializes the application automatically. You do need to initialize the app if you're using inline HTML data attributes or, if you're building your timeline programmatically (using Javascript/jQuery).

Sample JSON Configuration File:


{
  "lastupdated": "2026-01-22T15:53:04.030Z",  
  "timelineName": "",
  "layoutMode": "vertical",
  "moveItems": 1,
  "startIndex": 0,
  "horizontalStartPosition": "top",
  "verticalStartPosition": "left",
  "verticalTrigger": "15%",
  "sameSideNodes": false,
  "minWidth": 600,
  "maxWidth": 600,
  "nodeColor": "",
  "lineColor": "",
  "navColor": "",  
  "rtlMode": false,
  "useSwiper": false,
  "nodes": [
    {
      "id": 1,
      "ariaLabel": "",
      "date": "",
      "heading": "",
      "summary": "",
      "content": "",
      "image": ""
    },
    {
      "id": 2,
      "ariaLabel": "",
      "date": "",
      "heading": "",
      "summary": "",
      "content": "",
      "image": ""
    },
    {
      "id": 3,
      "ariaLabel": "",
      "date": "",
      "heading": "",
      "summary": "",
      "content": "",
      "image": ""
    }
  ]
}

More Examples Using A JSON Config File

Here are some more examples of timelines created using an external JSON configuration file.

The next section demonstrates how to generate ISO 8601 dates properly so you can update the lastupdated field of your JSON config file.