Download HistropediaJS

Choose Your Setup

Install the package, use the CDN, or download the bundle for self-hosted files.

Install from npm

Use the ESM package in modern bundlers and ESM-capable runtimes.

Shell

npm install histropediajs

JavaScript

import { Timeline } from 'histropediajs';

Choose this option for Vite, Webpack, Rollup, Parcel, or other build-tool based projects.

Use a Script Tag

Load the UMD build from the standard npm CDN.

HTML

<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
<script>
  const { Timeline } = Histropedia;
</script>

Choose this option when you want HistropediaJS available as a global browser variable without using imports.

Download Bundle

Download the files and host them yourself.

The bundle includes both ESM and UMD builds, so you can use it with either module imports or a script tag while serving the files from your own site.

ESM Self-hosted module import

JavaScript

import { Timeline } from './histropedia.esm.js';

UMD Self-hosted script tag

HTML

<script src="./histropedia.umd.min.js"></script>
<script>
  const { Timeline } = Histropedia;
</script>

Grab the bundle from the licence section below.

What's Inside

Everything you need to start building timelines, bundled into a .zip download.

histropediajs-1.4.0/

dist/ Production builds

UMD Use with <script> tags

histropedia.umd.min.js 161 kB ~46 kB gzip
histropedia.umd.js unminified, 337 kB

ESM Use with modern bundlers

histropedia.esm.js 313 kB ~65 kB gzip

TS TypeScript definitions

histropedia.esm.d.ts TypeScript definitions

demo/ Working examples

Complete UMD and ESM examples with shared data — copy, paste, and customize.

What's New

Highlights from the latest release. For full notes, see the links below or the change log.

Version 1.4.0 29th Apr 2026

v1.4.0 release blog post

Highlights

Multi-lane timelines – organize events into separate horizontal lanes while sharing one bottom timeline axis.
Lane layout and reordering APIs – add, style, hide, show, and reorder lanes at runtime.
Date range fitting – use timeline.fitDateRange(start, end, options) to fit a supplied period into the viewport.
Pan momentum and smoother wheel zooming – drag and notched wheel interactions feel more responsive by default.
Responsive baseline distance and card layout breakpoints – adapt article spacing and card layout to the available height.
Simplified download bundle – UMD, minified UMD, ESM, and one TypeScript definitions file.

Version 1.3.3 4th Feb 2026

Fixes

Time Band opacity bleed – resets the canvas globalAlpha at the start of each Time Band draw so the overlay does not inherit the last rendered article's fade opacity when it has no image.

Version 1.3.2 25th Jan 2026

Fixes

Legacy event handler this context – preserves the timeline instance as this inside legacy event handlers to maintain backward compatibility.

Version 1.3.1 18th Dec 2025

Fixes

HiDPI shadows – aligns shadow dimensions with the canvas DPR for consistent size on high-density displays.
Card border toggles – prevents landscape cards from drawing borders when border width is set to 0.
Card height refresh – recalculates card height when border width changes to fix bottom alignment.

Version 1.3.0 4th Dec 2025

v1.3.0 release blog post

Highlights

Zero dependencies – now only a single HistropediaJS file required.
Card layouts – landscape layout and the ability to register custom layouts.
Time Bands – highlight and label different time periods on the timeline.
Event system – new EventManager API with 18 events.
HiDPI support – configurable high-resolution canvas rendering.
Image loading – redesigned loader and cache for a massive performance boost.
Zoom options – smooth trackpad scrolling with automatic detection.
TypeScript – full type definitions for IDE autocompletion and type safety.

Choose Your Setup

Install from npm

Use a Script Tag

Download Bundle

Free for Non-Commercial Use

What's Inside

What's New

Highlights

Fixes

Fixes

Fixes

Highlights

Read the Docs

See Examples