Events Documentation

Subscribe to timeline, article, zoom, and viewport events with documented payloads and callback migration notes.

Events & Handlers new

Subscribe prior to initialization with options.on, or at runtime with timeline.on(event, handler). Unsubscribe with timeline.off(event, handler). Some handlers receive the originating DOM event as the last argument.

Quick index

Reference

All public events grouped by category. Click any to jump to details.

Timeline timeline-click, timeline-dblclick, timeline-render-start, timeline-render-end, timeline-state-change
Article article-pointerenter/move/leave, article-click, article-dblclick, article-drag-start/drag/end, article-select
Zoom zoom, zoom-wheel, zoom-pinch-start, zoom-pinch, zoom-pinch-end
Viewport viewport-drag-start, viewport-drag, viewport-drag-end

Timeline

Lifecycle

Background interactions and notifications affecting the whole timeline.

  • timeline-click: TimelineClickPayload, originalEvent
  • timeline-dblclick: TimelineClickPayload, originalEvent – fires after timeline-click when the background receives a double-click.
  • timeline-render-start: RedrawContext – emitted before each draw cycle; drawCycleContext is not yet set.
  • timeline-render-end: RedrawContext – emitted after each draw cycle with drawCycleContext populated when available.
  • timeline-state-change new: SerializedState:string – emitted after meaningful state-changing interactions settle, including viewport drags, zoom gestures, animations, article drags, and article removal. It is not emitted on every movement frame.
timeline.on('timeline-click', ({ viewport }, evt) => {
  console.log('timeline-click', viewport, evt);
});

timeline.on('timeline-dblclick', ({ viewport }, evt) => {
  console.log('timeline-dblclick', viewport, evt);
});

timeline.on('timeline-render-start', (redrawCtx) => {
  const { canvasContext, top } = redrawCtx;
  // canvasContext is the actual CanvasRenderingContext2D used to draw the timeline
  console.log('render-start', top, canvasContext);
});

timeline.on('timeline-render-end', ({ canvasContext, drawCycleContext }) => {
  console.log('render-end', drawCycleContext, canvasContext);
});

timeline.on('timeline-state-change', (stateJson) => {
  console.log('timeline-state-change', JSON.parse(stateJson));
});

Payload

  • TimelineClickPayload
    • viewport: { x:number, y:number } – coordinates relative to the timeline canvas

  • RedrawContext
    • canvasContext: CanvasRenderingContext2D – the context used to draw the timeline.
    • top: number – vertical position of the timeline main line relative to the canvas.
    • drawCycleContext?: object – data about the current draw cycle (e.g. cached date coordinates).

Article

Interaction

Pointer entry/exit, clicks, and dragging on individual articles.

  • article-pointerenter / article-pointermove / article-pointerleave: article: Article, originalEvent
  • article-click: article: Article, originalEvent
  • article-dblclick: article: Article, originalEvent
  • article-select: article: Article – When a new article is selected on the timeline
  • article-drag-start / article-drag-end: article: Article, originalEvent
  • article-drag: article: Article, delta: DragDelta, originalEvent
timeline.on('article-pointerenter', (article, evt) => console.log('enter', article, evt));
timeline.on('article-pointerleave', (article) => console.log('leave', article));

timeline.on('article-click', (article, evt) => console.log('click', article, evt));

timeline.on('article-select', (article) => console.log('select', article));

timeline.on('article-drag', (article, { dx, dy, totalDx, totalDy }) => {
  console.log('drag', article, { dx, dy, totalDx, totalDy });
});

Payload

  • DragDelta
    • dx: number
    • dy: number
    • totalDx: number
    • totalDy: number

Zoom

Interaction

Track unified zoom changes and specific wheel/pinch gestures.

  • zoom-wheel: WheelPayload, originalEvent
  • zoom-pinch-start: PinchPayload, originalEvent
  • zoom-pinch: PinchPayload, originalEvent
  • zoom-pinch-end: PinchPayload, originalEvent
  • zoom: ZoomPayload
// Unified zoom stream
timeline.on('zoom', ({ zoom, zoomDelta }) => {
  console.log('zoom', zoom, zoomDelta);
});

// Pinch lifecycle
timeline.on('zoom-pinch-start', ({ centre, zoom }) => console.log('pinch start', centre, zoom));
timeline.on('zoom-pinch', ({ centre, zoomDelta, totalZoomDelta }) => console.log('pinch', centre, zoomDelta, totalZoomDelta));
timeline.on('zoom-pinch-end', () => console.log('pinch end'));

// Wheel steps
timeline.on('zoom-wheel', ({ centre, zoom, zoomDelta }, evt) => {
  console.log('wheel', centre, zoom, zoomDelta, evt);
});

Payloads

  • ZoomPayload
    • zoom: number – current zoom level
    • zoomDelta: number – change since previous update
  • WheelPayload
    • centre: { x:number, y:number } – canvas pivot
    • zoom: number
    • zoomDelta: number – change from before the wheel step
  • PinchPayload
    • centre: { x:number, y:number } – pinch centre (canvas coords)
    • scale: number – distance / startDistance
    • distance: number – current finger distance (px)
    • zoom: number
    • zoomDelta: number – per-frame delta
    • totalZoomDelta: number – accumulated since zoom-pinch-start
    • dx?: number – centre.x delta since previous frame
    • pointers: PointerEvent[]

Viewport

Interaction

Pan the visible window by dragging the canvas.

  • viewport-drag-start: ViewportDragPayload, originalEvent
  • viewport-drag: ViewportDragPayload, originalEvent
  • viewport-drag-end: ViewportDragPayload, originalEvent
timeline.on('viewport-drag-start', (payload) => console.log('drag-start', payload));
timeline.on('viewport-drag', ({ dx, totalDx }) => console.log('drag', dx, totalDx));
timeline.on('viewport-drag-end', (payload) => console.log('drag-end', payload));

// Legacy helper (prefer viewport-drag-end)
timeline.on('drag-end', (totalDx) => console.log('drag-end (legacy)', totalDx));

Payload

  • ViewportDragPayload
    • startToken: { unit:number, value:Histropedia.Dmy, length:number } – left edge token
    • offsetX: number – current internal horizontal offset (px)
    • dx?: number – per-frame horizontal delta (px; left positive)
    • totalDx?: number – accumulated since viewport-drag-start

Conventions & guarantees

Notes
  • Event names follow subject-action-phase: zoom-pinch-start, viewport-drag.
  • High-frequency interactions emit *-start, mid *, and *-end.
  • Payloads include only relevant keys. Per-frame deltas are dx, dy, zoomDelta.
  • Totals accumulate from the corresponding *-start (e.g. totalDx).
  • When provided, the original DOM event is always the last argument.
  • startToken is an internal timescale token; treat as opaque unless using Histropedia.Dmy.

Legacy Callbacks

The root timeline options still document deprecated callback shortcuts: onRedraw, onArticleClick, onArticleDoubleClick, and onSave. Prefer the options.on map or timeline.on(event, handler).

Need More Help?

If you can't find what you're looking for, browse the examples or contact us.

Contact Support Browse Examples