antv-g2-chart

G2 v5 Chart Visualization

Overview

G2 v5 is AntV's grammar-of-graphics charting library. It uses Spec Mode — a declarative, JSON-like configuration style. Generated examples should start from a complete spec; runtime code may later merge a local update through chart.options().

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

const chart = new Chart({ container: 'container', autoFit: true });
chart.options({
  type: 'interval',
  data: [{ genre: 'Sports', sold: 275 }],
  encode: { x: 'genre', y: 'sold' },
});
chart.render();

CDN Usage

<script src="https://unpkg.com/@antv/g2@5/dist/g2.min.js"></script>
<script>
  const chart = new G2.Chart({ container: 'container', autoFit: true });
  chart.options({
    type: 'interval',
    data: [{ genre: 'Sports', sold: 275 }],
    encode: { x: 'genre', y: 'sold' },
  });
  chart.render();
</script>

Content Retrieval Service

When using AntV G2 for data visualization, if you need to understand the concepts, usage, API, examples, and other aspects of G2 v5, you can use the provided context retrieval service. When using the skill, content is retrieved via an antv HTTP API server using GET requests.

• Host: https://sive.antv.antgroup.com
• Endpoint: /api/v1/context/retrieve
• Method: GET
• Parameters: query, library, topK, content, maxTokens

Retrieve reference documents by query (hybrid search = FTS + vector + RRF fusion).

curl "https://sive.antv.antgroup.com/api/v1/context/retrieve?query=bar+chart+stacked&library=g2"

Critical Rules

MUST: Use V5 Spec Mode ONLY

// ❌ WRONG — V4 chain API (deprecated, will not render)
chart.interval()
  .data([...])
  .encode('x', 'genre')
  .encode('y', 'sold')
  .style({ radius: 4 });

// ✅ CORRECT — V5 Spec Mode
chart.options({
  type: 'interval',
  data: [...],
  encode: { x: 'genre', y: 'sold' },
  style: { radius: 4 },
});

Multi-mark overlays use view + children

chart.options() supports incremental deep-merge updates, which is useful for runtime interaction. For generated one-shot code, provide a complete initial spec. To create independent overlay marks, use one type: 'view' with children; sequentially changing the root type does not create an overlay.

// ❌ WRONG — this changes one root mark from line to point; it does not overlay them
chart.options({ type: 'line', data, encode: { x: 'date', y: 'value' } });
chart.options({ type: 'point', data, encode: { x: 'date', y: 'value' } });

// ✅ CORRECT — children array for multi-mark
chart.options({
  type: 'view',
  data,
  children: [
    { type: 'line',  encode: { x: 'date', y: 'value' } },
    { type: 'point', encode: { x: 'date', y: 'value' } },
  ],
});

MUST: container is mandatory, chart.render() at the end

// ❌ WRONG — no container, no render
const chart = new Chart();
chart.options({ type: 'interval', data });

// ✅ CORRECT
const chart = new Chart({ container: 'container', autoFit: true });
chart.options({ type: 'interval', data, encode: { x: 'genre', y: 'sold' } });
chart.render();

MUST: Correct mark types only

Legal G2 marks: interval, line, area, point, rect, cell, text, image, path, polygon, shape, link, connector, vector, lineX, lineY, rangeX, rangeY, range, box, boxplot, density, heatmap, beeswarm, treemap, pack, partition, tree, sankey, chord, wordCloud, gauge, liquid. sunburst requires @antv/g2-extension-plot.

MUST: encode is an object, transform is an array

// ❌ WRONG
.encode('x', 'genre')
.transform: { type: 'stackY' }

// ✅ CORRECT
encode: { x: 'genre', y: 'sold' }
transform: [{ type: 'stackY' }]

MUST: labels is plural; range encodings use mark-appropriate channels

// ❌ WRONG
label: { text: 'sold' }

// ✅ CORRECT
labels: [{ text: 'sold' }]
// Interval / link ranges may use either a two-field array or y + y1.
encode: { y: ['start', 'end'] }
// RangeY explicitly uses y + y1.
encode: { y: 'start', y1: 'end' }

MUST: No d3 in user code

// ❌ WRONG — d3 is not exposed in user scope
const total = d3.sum(data, d => d.value);

// ✅ CORRECT — use native JS or G2 built-in transforms
const total = data.reduce((sum, d) => sum + d.value, 0);

MUST: No white/near-white fill, no padding as array

// ❌ WRONG
style: { fill: '#fff' }       // invisible on white background
padding: [40, 30, 40, 50]     // invalid in G2 v5

// ✅ CORRECT
encode: { color: 'group' }    // let G2 assign colors
padding: 40                   // single number or 'auto'

MUST: Transpose is a transform, not a coordinate type

// ❌ WRONG
coordinate: { type: 'transpose' }

// ✅ CORRECT
coordinate: { transform: [{ type: 'transpose' }] }

Default Aesthetics / 默认视觉基线

目标是默认清晰、克制、可读，而不是给每张图添加相同装饰。先遵守以下决策，再按需检索 default+aesthetics+design 获取完整示例。

注意区分两种“默认”。G2 引擎默认（theme/create.ts）是 line.lineWidth: 1、area.fillOpacity: 0.85、矩形 radius 无圆角；本节 Mark 基线里的 radius: 4 / lineWidth: 2 / fillOpacity: 0.5~0.6 是本 skill 的约定值，用来覆写引擎默认让生成示例更好看，必须显式写在 style 里，不是省略即生效。

1. 通用：container、完整初始 chart.options() spec、chart.render() 是必须项；普通嵌入式图优先 autoFit: true、theme: 'classic' 与 padding: 'auto'。classic 是为稳定视觉显式选择的浅色预设，不是引擎默认主题（引擎默认推断为 light）；深色容器使用 classicDark。两者共用同一套 category10 色板（首选 #5B8FF9），因此稳定主色在浅/深主题下都可用。
2. 颜色表达语义：仅当颜色表示独立的系列、状态或分组时使用 encode.color 和图例。单指标分类比较使用稳定单色（如 style.fill: '#5B8FF9'，作为样式值是合法的）并关闭颜色图例，避免彩虹柱和冗余图例。禁止的是把 hex 字符串存进数据后作为 encode.color 的类别字段编码。
3. Mark 基线（约定值，覆写引擎默认）：interval 用 radius: 4（引擎默认无圆角）；line 用 lineWidth: 2（引擎默认 1）；area 用 fillOpacity: 0.5~0.6（引擎默认 0.85，偏实，降下来更透气）。这些值都需显式写在 style 里，不是省略即生效；不需要渐变、阴影或自定义动画。
4. 文本只用已知语义：字段/单位/来源明确时，添加语义化轴标题、tooltip 名称和 formatter；报告语境或用户提供标题时添加顶层 title。信息未知时省略，不编造单位、来源或副标题。
5. 标签按密度选择：少量且需精确读取的数据可加标签；密集散点、多系列折线、类别很多时默认依赖 tooltip。inside 标签用 contrastReverse，发生碰撞时使用 overlapHide / overlapDodgeY / overflowHide；dx / dy 只用于避让后的细微调整。
6. 特殊图：饼/环图的少量类别优先外置标签，类别较多时改用 legend；不要默认同时重复两者。气泡图保持 G2 默认 sqrt size 映射，按数据范围设置 size.range，仅在 size legend 无助理解时隐藏它。

渐变、阴影、滑块、滚动条、自定义动画和 3D 气泡都属于用户明确要求“报告级 / 精致”时的增强项；添加前必须确认不会掩盖数据或降低标签对比度。

Quick Reference

Dependencies

• @antv/g2 — G2 v5 charting engine