G2

@antv/g2 (G2) is a TypeScript visualization library named after and inspired by Leland Wilkinson’s The Grammar of Graphics. Instead of exposing one configuration option per named chart type, it defines a small set of orthogonal primitives — marks, encodings, scales, coordinates, transforms, and compositions — that combine to describe any visualization declaratively, then progressively allows deeper low-level overrides on the same object model.

Rendering is delegated to the sibling @antv/g engine family, so a single G2 spec can target Canvas, SVG, or WebGL without changing application code. Interactions and data-driven animations are built directly into the grammar rather than bolted on as chart-level callbacks, and the project is maintained by the AntV team with a large, active community and an unusually thorough automated test suite covering unit, integration/snapshot, and visual-regression tests.

What You Get

• A declarative Chart API (chart.interval().data().encode()) for building visualizations from composable marks, encodings, scales, coordinates, and transforms instead of fixed chart-type configs
• Multiple rendering backends (Canvas, SVG, WebGL) via the sibling @antv/g engine, selectable without changing your chart spec
• Built-in data-driven animation and a rich interaction system (tooltip, brush, legend filtering, and more) defined as first-class grammar concepts
• A pluggable library/registration system (extend, register) so marks, transforms, scales, coordinates, and interactions can be swapped or extended per project
• A large catalog of runnable examples and an official docs site covering the full API surface and chart gallery
• First-class TypeScript types for the entire spec object, enabling autocomplete and compile-time validation of chart configuration

Common Use Cases

• Building analytics dashboards and BI-style reporting UIs that need many closely related but non-identical chart variants
• Powering interactive data-exploration tools where users filter, zoom, or drill into visualizations at runtime
• Rendering data-driven storytelling and presentation graphics with custom animation sequences
• Serving as the charting layer beneath higher-level component libraries (e.g. ant-design-charts, g2-react) for React/Vue apps
• Rapid prototyping of novel or non-standard chart forms that off-the-shelf “chart type” libraries don’t expose directly

Under The Hood

Architecture G2 is built around a Mark/Runtime/Chart abstraction: a declarative spec (src/spec/*) describing marks, encodings, scales, coordinates, and transforms is normalized and pushed through the runtime layer (src/runtime/mark.ts, scale.ts, coordinate.ts, layout.ts, component.ts, render.ts), which composes visual channels into a scenegraph rendered by the separate @antv/g engine (Canvas/SVG/WebGL). The Chart class (src/api/chart.ts) is produced by extend(Runtime, library), binding a pluggable “library” of marks/transforms/scales/coordinates/interactions (src/lib) so users compose charts declaratively while an internal update/render lifecycle (runtime/plot.ts, runtime/render.ts) diffs and re-renders on data or option changes. This mark/transform/scale/coordinate separation is genuinely layered — the plugin-style library registration isolates the blast radius of changes to any one primitive, though core abstraction changes (e.g. to the mark pipeline) still ripple through the encode/scale/interaction layers built on top of it.

Tech Stack The source is TypeScript throughout (roughly 87% of the codebase), built via a dual pipeline — Rollup for the UMD bundle (rollup.config.js) and tsc for CJS/ESM outputs (build:cjs/build:esm) — producing lib/, esm/, and dist/ artifacts. Rendering is delegated to the sibling @antv/g rendering-engine family (@antv/g, @antv/g-canvas, @antv/g-plugin-dragndrop, with g-svg/g-webgl/g-plugin-3d available as optional renderers), while @antv/scale, @antv/coord, @antv/component, and @antv/expr supply the scale/coordinate/component/expression primitives, @antv/event-emitter provides the internal event bus, and small utility dependencies (flru, pdfast) handle caching and path-data parsing. Local development uses Vite (including a dedicated playground mode), Vitest with Istanbul coverage for tests, ESLint plus Prettier for style, and Husky/commitlint/lint-staged for commit hygiene; the documentation site under site/ is built and deployed independently.

Code Quality The test suite is unusually comprehensive for a visualization library: unit tests per module (__tests__/unit/api, scale, coordinate, encode, runtime, shape, lib, palette, utils), snapshot-based integration tests comparing rendered SVG/HTML output against golden files, and a large __tests__/plots suite that visually regression-tests hundreds of example chart specs across legend, tooltip, animation, interaction, and bugfix categories — around 150 test files in total. CI runs lint, test, and build on every push/PR (.github/workflows/build.yml). Types are used pervasively across the full TypeScript source with exported .d.ts declarations; ESLint (typescript-eslint) and Prettier enforce consistent style, and lint-staged/husky block unformatted commits. Correctness leans on the type system to prevent invalid spec shapes at compile time rather than on extensive runtime try/catch, which keeps the code clean but means some malformed runtime data can still surface as silent no-ops in edge-case transforms. Naming throughout is consistent and grammar-driven (mark/encode/scale/transform/coordinate) matching the project’s conceptual model.

What Makes It Unique G2’s core differentiator is committing fully to a grammar-of-graphics model — marks, encodings, scales, coordinates, transforms, and compositions as orthogonal primitives — rather than the “chart-type” typology most JavaScript charting libraries expose, letting a handful of composable building blocks describe arbitrary chart forms instead of one configuration surface per named chart. Its “progressive” API design supports both minimal one-line chart declarations and deep low-level overrides on the same object model, rendering is cleanly separated into the sibling @antv/g engine so an identical spec can target Canvas, SVG, or WebGL, and data-driven animation and interaction are first-class grammar concepts rather than chart-level callbacks — a design lineage closer to academic visualization-grammar research (the project has a published paper describing it) than to typical consumer charting libraries.