vis-timeline

vis-timeline is a JavaScript visualization library for rendering interactive timelines and Graph2D line charts of time-based data. Items can represent single points in time or ranges with a start and end, and users can drag, zoom, create, edit, and delete them directly in the browser without hand-rolling custom canvas or SVG interaction code.

The library ships as four separate builds - standalone, peer, ESNext, and a deprecated legacy bundle - so it can be dropped into a plain HTML page via a script tag or imported into a bundler-based project with peer dependencies on vis-data, moment, and hammer.js resolved by the consuming app. It powers Gantt-chart-style scheduling views, log and event timelines, and time-series monitoring dashboards across a wide range of open-source and commercial products.

What You Get

• Timeline and Graph2D components that share one time axis, one group/stacking engine, and one zoom-and-pan Range controller
• DataSet/DataView-driven rendering (via vis-data) that reacts automatically to external additions, updates, and removals
• Built-in editing interactions - move, resize, add, and delete items - with configurable callbacks and validation hooks
• Grouping, subgrouping, and automatic vertical stacking to keep overlapping items readable
• Four prebuilt distribution formats (standalone, peer, ESNext, legacy) plus hand-written TypeScript declarations

Common Use Cases

• Gantt-style project and resource scheduling boards
• Incident, deployment, and log timelines that correlate events across systems
• Time-series sensor or metrics charting via the Graph2D component
• Booking and reservation calendars with drag-to-edit ranges

Under The Hood

Architecture Core.js (~1,550 lines) is the shared base class that both Timeline and Graph2d extend, giving the two visualizations one render loop, one Range (pan/zoom) controller, and one Stack collision-layout engine instead of duplicating that machinery per chart type. Visual subsystems - ItemSet, LineGraph, Group, TimeAxis, DataAxis, CurrentTime, CustomTime, Legend, ClusterGenerator - are separate components under lib/timeline/component that all implement a shared Component redraw/repaint lifecycle Core drives centrally. Data flows in from vis-data DataSets/DataViews through Core’s change listeners into ItemSet/LineGraph, which recompute layout via Stack and repaint through the common Component contract, so replacing that render-loop or Component interface would ripple through every visual subsystem at once.

Tech Stack The library is plain ES-module JavaScript (“type”: “module”) targeting the browser DOM, built with Rollup (rollup.config.js / rollup.build.js) into UMD and ESM bundles across four distribution trees. Runtime dependencies are resolved as peers: vis-data for reactive DataSets, vis-util for shared helpers, moment.js for date parsing/formatting/locales, @egjs/hammerjs plus propagating-hammerjs for touch and gesture handling, keycharm for keyboard shortcuts, component-emitter for its internal event bus, uuid for id generation, and xss for sanitizing user-supplied HTML in item content. Linting and formatting run on oxlint/oxfmt (Rust-based tooling), with Husky and lint-staged wiring pre-commit checks and an autofix.ci GitHub Action that auto-fixes and pushes style issues on pull requests.

Code Quality Test coverage is thin relative to the surface area: only a handful of Mocha specs (Timeline, TimelineItemSet, TimelineRange, DataAxis, PointItem, TimeStep, Activator, plus a package and util-convert test) run against a jsdom-simulated DOM via jsdom-global, and most component/ subsystems - LineGraph, Group, ClusterGenerator, DataScale - have no dedicated test file. The codebase itself is untyped JavaScript; TypeScript declarations in types/ are hand-written and shipped separately rather than compiler-checked against the implementation. Error handling in the DOM-manipulation paths favors early-return guards and console warnings over thrown exceptions. Style is enforced via oxlint/oxfmt with pre-commit hooks, but there’s no dedicated CI workflow visible beyond the autofix job.

API Design The public surface is deliberately small: a single new Timeline(container, items, options) (or Graph2d) call using plain objects and DataSets gets a working, editable visualization with no required boilerplate. The project backs this up with an extensive examples directory covering data handling, editing, grouping, interaction, markers, and styling scenarios individually, which substantially lowers the cost of discovering the right option for a given use case even though the option surface itself is large.