LombokCharts

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 |

Contributing

See CONTRIBUTING.md.

License

Apache-2.0 © codinglombok — see LICENSE and NOTICE.