Download HistropediaJS

Free for non-commercial use

Click the button below to download HistropediaJS and get started.

If you're interested in using HistropediaJS for a commercial project, feel free to download and test HistropediaJS as much as you like but please contact us to discuss an appropriate licence before publishing any work online.

We hope you enjoy!


Content of Download

This download package includes the latest version of Histropedia.js (normal and minifed), the 2 required dependencies and a HTML example page.

  • histropedia-1.2.0.js
  • histropedia-1.2.0.min.js
  • jquery-3.5.1.min
  • jquery.mousewheel-3.1.13.min.js


See the documentation page for a description of all the options available and instructions on getting started, or the examples page for live demos of various settings.


Licence Agreement and Download

By downloading and using this software, you acknowledge your understanding and acceptance of the HistropediaJS Non-Commercial Licence Agreement. Please read this carefully before you proceed.

What's new?

Release blog postNewsletter announcement


Feature Details
Huge timeline redraw performance boost!

changed Timeline redraw has been significantly restructured to optimise performance. Previous versions hit performance issues on slower devices above around 10,000 events on the timeline. This is now up to 30,000 events, and can go considerably higher with the right settings! To top off the good news, the worst performing browsers have had the biggest improvement. So performance is now very consistent among all major browsers, with no need to set browser specific timeline options.

There is a new Timeline.requestRedraw() method that can be used to make the most of the performance enhancements within your own custom functions (see below).

Article Hover Style
Article style options

new The new hoverStyle works in exactly the same way as the existing style and activeStyle options. They can be set as defaults in your timeline options, and overriden for individual articles.
The new order of style inheritance/override is: style hoverStyle activeStyle

Article method

new Set an individual article's hover style any time after initialisation.

Timeline method

new This method allows you to request a redraw of the timeline, optionally specifing any built-in or custom redraw function to use. The redraw will be called directly or integrated into an animation if one is ongoing. This is now the recommended way to redraw the timeline as it gives the best performance.

NOTE: All previous timeline redraw functions can still be used normally, and have some performance improvements even without switching to Timeline.requestRedraw()

Timeline method

new New timeline redraw function with a good balance of functionality and performance. It performs the same steps as the basic Timeline.redraw() method, but includes repositioning of articles from the current time range. This means it can be used when the time range is changing, unlike Timeline.redraw().

NOTE: The most complete (and slowest) redraw is still Timeline.defaultRedraw(), which performs all the same steps as Timeline.repositionRedraw(), but also includes re-stacking of articles on the timeline.

Timeline method

new Similar to Timeline.goToDateAnim(), but for panning the timeline by a number of pixels instead of to a particular date.

Text alignment for article title and subtitle
Article style options

new New text align and baseline style options for controlling article title and subtitle.

Hide article subheader when height = 0
Article style options

new Disable drawing of the entire subheader by setting subheader.height to 0 in your article style options.
This means you can easily show/hide the subheader for different article states using your style, hoverStyle or activeStyle settings.

onRedraw event
Timeline options

new New event which fires when each timeline redraw has been completed, with handlers registered in your timeline options. The handler function has access to the canvas context and timeline state, so this feature is ideal for adding custom drawings to the timeline canvas.

Shift BCE dates by 1 year
Timeline options

new By setting options.shiftBceDates to true, all BCE input dates will be shifted by +1 year.

This allows you to use data with either the 1BCE = 0 or 1BCE = -1 convention.
The setting applies to all date input - e.g. in article data, timeline & article methods for setting dates, initial date in timeline options.

Allow function for draggingVicinity
Timeline options

changed The draggingVicinity timeline option will now accept a function or boolean value, as well as the original {up: x, down: y} syntax. The default value has been set to true, which enables dragging over the whole timeline canvas.

Allow function for autoStacking topGap
Timeline options

changed The article.autoStacking.topGap timeline option will now accept a function as well as a number.

Increase default mousewheel zoom speed
Timeline options

changed The default zoom.wheelSpeed timeline option has been increased to 3

Changed default mainLine size
Timeline options

changed The default style.mainLine.size timeline option has been increased by a single pixel to 8. Using even numbers for this setting avoids pixel rounding for the top and bottom of the mainLine, giving a sharp line instead of slightly blurred edges. This will be fixed in a future version but best to stick with even numbers where possible for now.


Bug fixed Details
Internet Explorer support lost in recent versions

Compatibility with Internet Explorer 11 and various other older browsers has been restored.

Timeline doesn't load if title missing in article data

The title property in article data is now optional. If not specified it defaults to an empty string "".

Timeline.setStartDate not using date fractions

When attempting to set a date that does land on a timeline marker, the fraction of the marker was not being calculated. This is now corrected, so the position reached on the timeline is correct to the pixel level.

Newsletter announcement


Feature Details
Timeline method
new Set Timeline options after initialising you're timeline. Options can be defined using an object, or as a 'path string' using dot notation (as with the other two new setting methods below).
Article method
new Set Article options after initialising you're timeline.
Article method
new Set individual Article styles after initialising you're timeline (use the new setOption Timeline method for changing default styles for all articles)
activeStyle inherits from normal style
Article style options
changed When using the Article style options, the activeStyle is now defined as an override to the normal style. This means that you no longer need to add a duplicate style setting to both style and activeStyle for things that don't change when active. Any previous activeStyles you have defined will still work, but will have some uneccessary options set that will now be inherited from the normal style.
Period line stacking
Timeline options
new New article.periodLine.stacking section in the Timeline options that lets you control how the 'period lines' on the timeline are stacked when their durations overlap. The default setting is to sort them by the from date, but you can choose from a range of other built in options (e.g. rank or duration). You can also define you're own custom sorting function if desired.
Selection of Article sorter functions
new You can now access a range of built in functions used for sorting the main articles array of any timeline (e.g. sort by from date, duration, rank etc). These can be used with the new periodLine stacking options described above, but are also very useful when creating custom functions.
You can access the new functions via the main Histropedia object - e.g. myTimeline.articles.sort( Histropedia.ARTICLE_RANK_SORTER )
Timeline method
changed You can now pass an object as an optional second parameter, with settings for the pan animation. The current options available are duration (animation duration in milliseconds), offsetX (control where the given date ends up on the screen), and complete (function to be called when animation is complete).


  • Various minor bug fixes