# antvis/G2: a grammar of graphics for web charts, not a chart-type library

> G2 declares marks, scales, coordinates and transforms instead of picking a chart from a catalogue. This looks at how that mechanism works, how to install it from npm, and where the declarative model costs you more than it gives.

**antvis/G2** — 📊 The concise and progressive visualization grammar.

- Repository: https://github.com/antvis/G2
- Website: https://g2.antv.antgroup.com
- Stars: 12,627 · Forks: 1,659
- Language: TypeScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/antvis-g2

## The problem G2 solves: charts as declarations, not as chart types

Most JavaScript charting libraries hand you a menu. You pick a bar chart component, pass an array, and configure options until it looks right. G2 takes the opposite route. The README states that G2 rejects a chart typology in favour of marks, transforms, scales, coordinates and compositions. There is no BarChart class to import. You create a Chart, add a mark such as interval, and assign data columns to visual channels.

The intended audience follows from that. The project describes itself as a visualization grammar for dashboard building, data exploration and storytelling, and the first listed feature is progressive usage: concise declarations get you a meaningful chart quickly, and the library infers the rest, while more configuration is available for complex cases. That is a reasonable fit for teams building a chart layer that has to survive many one-off requests, and a poor fit for anyone who wants a fixed catalogue of named components. If your requirement is literally "a bar chart component I can drop into a React page", the grammar is overhead you did not ask for.

The name is not decorative. The README says G2 is named after Leland Wilkinson's book The Grammar of Graphics and was profoundly inspired by it. The design commitment is stated up front, so the API shape should not surprise anyone who reads the introduction page before installing.

## How the grammar works: marks, encodes and a renderer called G

The mechanism is visible in the README's own example. A Chart is instantiated with a container. Marks are added to it by chaining methods. Each mark receives data and encodes, where an encode call binds a data column to a position or appearance channel such as x, y or color. Rendering is a separate, explicit step.

Underneath, the README describes a renderer named G that generates web-based visualizations using Canvas, SVG or WebGL. G2 is not drawing pixels itself; it delegates to G and inherits that library's plugin set, which the README connects to hand-drawn styles and to the D3 ecosystem. This is the part worth understanding before you commit, because it means the rendering backend is a choice you make, not a detail you ignore. Canvas and SVG are not interchangeable in cost or in output fidelity, and WebGL is a different proposition again.

Extensibility is stated as a first-class goal. The README claims a consistent mechanism to extend a scale, a transform or a mark, and says you can customize a brand new visualization tool on top of it. The grammar also covers more than static output: the README lists data-driven animations and action-based interactions as declarable parts of a plot. Treat those claims as documentation statements rather than verified behaviour; the repository's own test layout, with separate unit and integration directories, is the place to look if you need to know how much of that surface is exercised.

## Installing @antv/g2 and drawing a first chart

G2 is published to npm as @antv/g2. The README gives npm and Yarn as the package managers, so the install is a single command either way.

```bash
npm install @antv/g2
```

Yarn works the same way, per the README.

```bash
yarn add @antv/g2
```

You need a container element in the page before the chart is created. The README's example uses a div with the id container.

```html
<div id="container"></div>
```

Then import Chart, build a small tabular array, and chain the mark and its encodes. The README's example uses a five-row games dataset with genre and sold columns.

```js
import { Chart } from '@antv/g2';

const data = [
  { genre: 'Sports', sold: 275 },
  { genre: 'Strategy', sold: 115 },
  { genre: 'Action', sold: 120 },
  { genre: 'Shooter', sold: 350 },
  { genre: 'Other', sold: 150 },
];

const chart = new Chart({ container: 'container' });

chart
  .interval()
  .data(data)
  .encode('x', 'genre')
  .encode('y', 'sold')
  .encode('color', 'genre');

chart.render();
```

The README states that if all goes well you get a bar chart from this. Two things are worth noting about the shape of the code. First, render is explicit; nothing draws until you call it. Second, the mark is interval, not "bar". That naming is the grammar showing through, and it is the first place a newcomer will stumble. The README points to an examples gallery and an interactive quick-start guide for the concepts beyond this snippet, and the API reference is where the full component list lives.

## Where G2 is the wrong tool

The grammar is the cost. Every chart begins with a mental translation from "I want a stacked area chart" to a set of marks, encodes and possibly transforms and coordinates. For a one-off chart in a marketing page, that translation is pure overhead compared with a library that ships the chart type directly. The README's own framing supports this reading: progressive usage is described as a goal, which implies the simple path is a deliberate design target rather than an accident, but the simple path still requires you to learn the vocabulary.

Rendering is another boundary. Because G2 delegates to G and supports Canvas, SVG and WebGL, the behaviour of your chart depends on a backend choice that the README does not resolve for you. If you need to export static SVG for print, or if you are targeting environments where WebGL is unavailable, that decision has to be made explicitly and tested. The README does not document a default renderer in the excerpt available, so verify it against the API reference rather than assuming.

Finally, the ecosystem answer is often the honest one. The README lists ant-design-charts as a React chart library built on G2, G6, X6 and L7Plot, and g2-react as a lightweight React component for G2. If your problem is React integration rather than grammar, you are looking at the wrong repository. G2 is the engine; those projects are the product.

## How G2 differs from a chart-type library

The clearest contrast inside the material is ant-design-charts. It is described as a React chart library based on G2, G6, X6 and L7Plot. The difference in approach is not a matter of quality; it is a difference in what you are handed. ant-design-charts gives you React components that correspond to chart types and wire them into the React tree. G2 gives you a Chart object and a set of declarative methods, and leaves the integration to you or to a wrapper such as g2-react.

That has a practical consequence. With a chart-type library, a request for a new chart shape is a matter of finding the right component or filing a feature request. With G2, a request for a new chart shape is a matter of composing marks, transforms and coordinates yourself, which the README presents as the point of the design. The trade is control against convenience, and it is a real trade rather than a marketing one.

The same logic applies to the wider AntV family named in the README. G6 and X6 and L7Plot solve graph, diagram and map problems respectively. G2 is the general-purpose statistical chart layer. If your visual is a network graph or a geographic map, the grammar is not the tool you want, even though the projects share an organisation and a renderer lineage.

## Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-21. The most recent release listed is v5.4.8 from 2026-01-06, preceded by v5.4.7 on 2025-12-09 and v5.4.6 on 2025-11-26. The gap between the latest release and the latest push means the default branch v5 carries work that has not been published, which is normal for a project of this shape but worth knowing if you pin to a version.

The package is MIT licensed, stated in both the README and package.json. That is permissive and places few obligations on how you redistribute it, but it is not legal advice and your own compliance review is the only thing that governs your use.

Upgrade cost is where the grammar cuts both ways. The package.json exports map separates lib (CommonJS), esm and dist builds, with types pointing at lib/index.d.ts. Consuming the wrong entry point under a bundler that does not respect the exports field is a real failure mode. On the API side, a declarative grammar tends to be more stable than a component prop surface, because you compose primitives rather than configure a fixed component, but that is a property of the design and not a promise the material makes. The CHANGELOG.md at the repository root is where release-to-release changes are recorded.

## Conclusion

Adopt G2 when your charts need data-driven animation, custom marks or a non-standard composition that a fixed chart-type library cannot express, and when you are comfortable reading the API reference rather than copying a component name. Do not adopt it if your team wants a drop-in React chart component with a prop for every option; ant-design-charts exists for that and wraps G2 for you. Before committing, verify three things in your own environment: that the Chart import path resolves under your bundler, that the container element has a measurable size at first render, and that the renderer you need (Canvas, SVG or WebGL) is the one your target browsers actually support.

## FAQ

### What is antvis/G2?

G2 is a visualization grammar for dashboard building, data exploration and storytelling, written in TypeScript and published to npm as @antv/g2. The README states it rejects a chart typology in favour of marks, transforms, scales, coordinates and compositions.

### How do I install antvis/G2?

The README gives npm and Yarn: npm install @antv/g2, or yarn add @antv/g2. You then import Chart from @antv/g2 and instantiate it against a container element.

### Is antvis/G2 a React chart component?

No. G2 exposes a Chart object and a declarative method chain, and the README lists g2-react as a lightweight React component for G2 and ant-design-charts as a React chart library built on G2 and other AntV projects.

## Sources

- [antvis/G2 on GitHub](https://github.com/antvis/G2)
- [License: MIT](https://github.com/antvis/G2/blob/v5/LICENSE)
- [Project website](https://g2.antv.antgroup.com)
- [README](https://github.com/antvis/G2/blob/v5/README.md)
- [Releases](https://github.com/antvis/G2/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/antvis-g2