README

Universal zero-dependency charting library — Canvas/SVG, LTTB decimation, real-time streaming. Part of Lombok Ecosystem. Apache-2.0.

GitHub

npm

SourceForge

Packagist

Quality

Community

git clone https://github.com/codinglombok/LombokCharts.git

A zero-dependency charting library for the browser. It pairs a small grammar-of-graphics core (Data → Scale → Mark) with pluggable Canvas and SVG renderers, LTTB decimation, and a real-time streaming layer — so the same API draws a five-point bar chart or a five-million-point line without changing shape.

Zero runtime dependencies. Native Canvas2D / SVG / ResizeObserver / requestAnimationFrame / typed arrays only.
Two renderers, one API. Canvas by default (fast path for huge series), SVG when you want crisp vector output or DOM-inspectable nodes.
Scales from tiny to massive. Typed-array pipeline plus Largest-Triangle-Three-Buckets (LTTB) decimation keeps million-point series interactive.
Real-time built in. appendData, async iterators, EventSource, or WebSocket, with a ring buffer for constant-memory sliding windows.
Tree-shakeable. Register only the marks you use and the rest is dropped by your bundler.
~19 KB gzipped for the full build with every mark registered; far less for a custom subset.

Why this library? (Mengapa library ini?)

LombokCharts is a standalone, general-purpose charting library for anyone who needs to turn numbers into pictures — web developers, data/BI teams, fintech and trading desks, SRE and monitoring dashboards, IoT and industrial HMI/kiosk panels, scientific and education tools, and government or NGO open-data portals. It is not tied to any single application or framework.

Problem	How LombokCharts solves it
Chart libraries pull in large dependency trees	Zero runtime dependencies, ~19 KB gzip full build, tree-shakeable marks
Libraries are fast or crisp, not both	One API over Canvas (millions of points) and SVG (vector, inspectable)
Millions of points freeze the browser	Typed-array pipeline + LTTB / min-max decimation
Live data needs custom plumbing	Built-in ring buffer, rAF-coalesced `appendData`, WebSocket / SSE / async iterator
Charts are English-only and inaccessible	Opt-in i18n (Core-20 + Nusantara, RTL), ARIA role/summary, locale-aware ticks
Logic cannot be reused outside JS	Pure DOM-free core with a normative SPEC + cross-language test vectors for ports

Compared with Chart.js, ECharts, uPlot, Plotly and D3, LombokCharts is the only one that combines zero dependencies, a grammar-of-graphics core, dual Canvas/SVG output, built-in LTTB streaming and cross-language test vectors for porting the pure core.

Quick Start

npm / bundler

npm install lombok-charts

import { chart } from "lombok-charts";

chart("#app", {
  mark: "bar",
  data: [
    { label: "Q1", value: 120 },
    { label: "Q2", value: 200 },
    { label: "Q3", value: 150 },
    { label: "Q4", value: 280 },
  ],
  title: "Quarterly Revenue",
});

CDN (no build step)

<div id="app" style="width:600px; height:400px"></div>
<script src="https://cdn.jsdelivr.net/npm/lombok-charts/dist/lombok-charts.umd.min.js"></script>
<script>
  LombokCharts.chart("#app", {
    mark: "bar",
    data: [
      { label: "Q1", value: 120 },
      { label: "Q2", value: 200 },
      { label: "Q3", value: 150 },
      { label: "Q4", value: 280 },
    ],
  });
</script>

Other CDN options (pinned version, ESM, unpkg) are listed in DISTRIBUTION.md.

Composer (PHP projects)

composer require codinglombok/lombok-charts

Then reference vendor/codinglombok/lombok-charts/dist/lombok-charts.umd.min.js in your HTML.

Chart Types

Family	Marks
Bar	column, horizontal bar, grouped, stacked, waterfall
Line	line, step, spline (Catmull-Rom), slope
Area	area, stacked, streamgraph
Point	scatter, bubble
Arc	pie, donut, gauge, radial bar
Statistical	histogram, box plot
Financial	candlestick (OHLC)
Specialized	radar, heatmap, funnel, treemap, sankey

Pick a mark with the mark option: a shorthand string ('donut', 'stacked-bar', 'spline') or an object with extra settings ({ type: 'gauge', value: 72, min: 0, max: 100 }).

Examples

Multi-series line:

chart("#chart", {
  mark: "line",
  data: rows, // [{ month:'Jan', sales: 10, cost: 6 }, ...]
  x: "month",
  series: [
    { key: "sales", label: "Sales" },
    { key: "cost", label: "Cost" },
  ],
});

Donut chart:

chart("#chart", {
  mark: "donut",
  data: [
    { label: "Mobile", value: 58 },
    { label: "Desktop", value: 32 },
    { label: "Tablet", value: 10 },
  ],
});

Large dataset with typed arrays (LTTB kicks in automatically):

const xs = new Float64Array(1_000_000);
const ys = new Float64Array(1_000_000);
// ...fill...
chart("#chart", { mark: "line", xs, ys, count: 1_000_000 });

Real-time stream with sliding window:

const c = chart("#chart", { mark: "line", maxPoints: 2000 });
setInterval(() => c.appendData({ x: Date.now(), y: read() }), 16);
// or: c.stream(new WebSocket('wss://…'), (msg) => ({ x: msg.t, y: msg.v }));

Theming and export:

c.setTheme("dark");
const png = c.toPNG(); // data URL
const svg = c.toSVG(); // serialized <svg> markup

Internationalization

English is built in. The other 22 catalogs (Core-20 + jv, su, ms) are opt-in, so they add nothing to your bundle unless you load them (~1.8 KB gzip for all of them):

import { chart, registerLocales } from "lombok-charts";
import { LOCALES } from "lombok-charts/i18n";

registerLocales(LOCALES);            // all languages, or just one: registerLocales({ id: LOCALES.id })
chart("#app", { mark: "bar", data, title: "Omzet", locale: "id-ID" });
// a11y summary: "Omzet: grafik bar dengan 1 seri, 4 titik data."
// y ticks via Intl.NumberFormat (compact) — "1,5 rb"; Arabic/Urdu set dir="rtl".

With script tags, load the add-on after the main bundle; it registers every catalog automatically:

<script src="https://cdn.jsdelivr.net/npm/lombok-charts/dist/lombok-charts.umd.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/lombok-charts/dist/lombok-charts-i18n.umd.min.js"></script>

Opt-in catalogs: zh, hi, es, fr, ar, bn, pt, ru, ur, id, de, ja, sw, mr, te, tr, ta, vi, ko (Core-20 with en) plus jv, su, ms (src/i18n/locales.js). Add your own with registerLocale("nl", { noData, chart, summary }).

API at a Glance

chart(container, config) -> Chart        // factory; same as new Chart(container, config)

Chart#render()                           // (re)draw, animating on first paint
Chart#update(data | { xs, ys, count })   // replace data and redraw
Chart#appendData(point | point[])        // live append (coalesced to one redraw/frame)
Chart#stream(source, map?)               // async iterator | EventSource | WebSocket
Chart#setTheme('light' | 'dark' | {...}) // swap theme tokens (deep-merged)
Chart#resize()                           // re-measure container (also automatic via ResizeObserver)
Chart#toPNG() / Chart#toSVG()            // export
Chart#on('hover' | 'select' | 'append', fn)
Chart#destroy()                          // remove listeners, observers, DOM

Full reference: docs/api.md. Theming: docs/theming.md. Internals and how to add a mark: docs/architecture.md. Porting the pure-logic core to other languages: docs/porting.md.

Performance

The Canvas renderer has a typed-array fast path (polylineTyped / pointsTyped) that avoids per-point allocations, and line/area/scatter marks decimate with LTTB when the series has more points than the plot has horizontal pixels to show them. Animation is disabled automatically above 50,000 points so the first paint stays responsive.

General guidance: Canvas + LTTB is the default for anything above a few thousand points; SVG is best below a few thousand or when you need vector output. The repo includes a live benchmark at examples/stress.html — choose 100k / 1M / 5M points, toggle LTTB, and switch Canvas vs SVG.

Bundle Size

Build	File	Raw	Gzipped
ESM (min)	`dist/lombok-charts.esm.min.js`	~58 KB	~19 KB
UMD (min)	`dist/lombok-charts.umd.min.js`	~59 KB	~20 KB
i18n add-on (optional)	`dist/lombok-charts-i18n.umd.min.js`	~5 KB	~2 KB

These cover the full library with all 13 marks registered. Importing Chart plus only the marks you need lets your bundler tree-shake the rest for a smaller footprint.

Development

npm install      # dev-only: esbuild
npm run build    # -> dist/ (esm, esm.min, umd, umd.min, cjs)
npm test         # zero-dependency test runner (unit + headless DOM smoke)
npm run dev      # watch build

The dist/ folder is committed so that Composer, jsDelivr-from-GitHub, and <script> users can consume it without a build step; CI regenerates it on every push to keep it in sync with src/.

Roadmap

See ROADMAP.md for the full 0.1 → 1.0 plan. Next priorities:

Visual regression testing with Playwright (0.2)
TypeScript declarations and API hardening (0.3)
Full ARIA accessibility and keyboard navigation (0.4)
WebGL renderer for extreme point counts (0.5)
Framework wrappers: React, Vue, Svelte, Angular (0.6)

Standards implemented

Standard	Where
WAI-ARIA 1.2 (`role="img"`, `aria-label`, `aria-pressed`)	chart surface, legend toggles
BCP 47 language tags + ECMA-402 `Intl.NumberFormat`	`config.locale`, tick labels
W3C SVG 1.1 / 2	`SvgRenderer`, `toSVG()`
WHATWG HTML Canvas 2D, W3C PNG (ISO/IEC 15948)	`CanvasRenderer`, `toPNG()`
WHATWG Server-Sent Events, RFC 6455 WebSocket	`chart.stream(...)`
ECMAScript 2021 (ECMA-262), ES modules + CommonJS + UMD	`dist/` builds
Semantic Versioning 2.0, Conventional Commits, Keep a Changelog	release process

Behavior of the portable core is pinned by the cross-language vectors in vectors/lombokcharts-vectors-v1.json (checked by tests/vectors.test.js).

Lombok Ecosystem

LombokCharts works alongside other Lombok Ecosystem libraries — they are optional companions, never required dependencies (and none of them owns LombokCharts):

Project	Description
	PHP 8.3+ full-stack framework — 31 packages, Apache-2.0
	Token-first CSS framework — npm + RubyGem + jsDelivr
	Zero-dependency charting — Canvas/SVG, LTTB, streaming
	Pure-JS QR code + Code128 barcode toolkit
	Spreadsheet engine — formulas, i18n, ANOVA, plugins
	Modular web animation library — scroll, parallax, morph
	Reed-Solomon (255,239) — TS + PHP + Python + Go + Rust + C++
	PDF generation and manipulation toolkit