Getting Started Documentation

Installation

1. Install from npm

For bundlers and ESM-capable runtimes, install the package from npm:

npm install histropediajs

2. Load the library

Use ESM imports with a bundler, or load the UMD build from a CDN for script-tag embeds.

import Histropedia, { Timeline, Dmy } from 'histropediajs';

const container = document.getElementById('timeline');
const timeline = new Timeline(container);

console.log(Histropedia.Timeline === Timeline);

<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
<script>
  const container = document.getElementById('timeline');
  const timeline = new Histropedia.Timeline(container);
</script>

<script type="module">
  import Histropedia, { Timeline, Dmy } from 'https://cdn.jsdelivr.net/npm/[email protected]/dist/histropedia.esm.js';

  const container = document.getElementById('timeline');
  const timeline = new Timeline(container);
</script>

HistropediaJS is published as an ESM package for npm and bundlers. CommonJS require('histropediajs') is not supported.

For non-module browser usage, use the UMD script-tag build shown above, or self-host histropedia.umd.js / histropedia.umd.min.js.

TypeScript definitions are included with the npm package. The download bundle also includes histropedia.esm.d.ts for direct ESM usage.

CDN URLs

For direct CDN imports, you can target the package default or a specific build file:

https://cdn.jsdelivr.net/npm/[email protected]
https://cdn.jsdelivr.net/npm/[email protected]/dist/histropedia.esm.js
https://cdn.jsdelivr.net/npm/[email protected]/dist/histropedia.umd.js
https://cdn.jsdelivr.net/npm/[email protected]/dist/histropedia.umd.min.js

Core Concepts

Understand the core concepts that power HistropediaJS.

Timeline

The Timeline is the engine that renders and manages the interactive canvas. Creating a Timeline instance is the first step and provides the foundation for configuration, loaded Articles, Lanes, Time Bands, event listeners, and other features.

You can create multiple timelines on the same page, each with its own configuration, data, and render state.

API reference: Timeline Options, Timeline Methods

Article

An Article is a single item on the timeline, representing an event which may be an instant or a period of time. Articles are added to the timeline using the timeline.load method and follow the Article Schema.

Each Article appears as a card attached to a period line that represents its time span. Article options control behaviour and the type of card layout ("portrait", "landscape", or a custom layout) and article styles define the appearance for whichever layout has been selected.

API reference: Load Articles Method, Article Schema, Article Options, Article Style

Lane new

A Lane is a horizontal section for grouping related Articles while preserving one shared bottom timeline axis. Lane's have backgrounds which are created as DOM elements underneath the timeline canvas so they can easily be styled via CSS if preferred.

Define explicit lanes with options.lane.data or timeline.loadLanes, then load articles usingtimeline.loadLaneArticles. Alternatively, use the standard timeline.load method with a lane key on each article. Articles without a lane use options.lane.defaultId. If an article references a lane id that has not been defined yet, HistropediaJS automatically creates an implicit lane for that id.

You can also move an article between lanes after loading it with article.setOption("lane", laneId).

API reference: Lane Options, Lane Schema, Lane Methods

Time Band new

A Time Band is a background band used to mark broad periods or eras, shown beneath the main timeline line by default.

Time Bands are loaded using the timeBand.data option or the timeline.loadTimeBands method, following the Time Band schema.

API reference: Load Time Bands Method, Time Band Schema, Time Band Options, Time Band Style

Charts new

Charts add read-only quantitative layers that share the timeline's horizontal date scale. A Chart contains one or more series of dated values and renders as a line or area chart with its own y-scale.

Load charts during construction with options.chart.data or after construction with timeline.loadCharts. To draw charts inside a Lane, set ChartData.lane and use timeline.loadCharts, or use timeline.loadLaneCharts to apply the lane id as the charts are loaded. Charts without a lane use the main chart area.

Charts are visual-only layers. They do not affect article stacking and are not interactive, so they cannot be hovered, clicked, selected, or dragged.

API reference: Chart Options, Chart Schema, Chart Style, Chart Methods