antv-gpt-vis

GPT-Vis Chart Visualization Skill

GPT-Vis is an AI-native visualization library designed for the LLM era. It uses a framework-agnostic architecture, supports 26 chart types, and enables LLMs to easily generate high-quality visualizations through a simple, natural syntax.

Steps

1. Intent recognition: Select the chart type based on user intent and data characteristics
2. Determine output mode: Choose Syntax mode or Code mode based on context
3. Generate output: Produce content in the selected mode

Supported Chart Types

Output Modes

Mode 1: Syntax Mode (Syntax / JSON)

Used for LLM application integration scenarios. Generates chart configurations consumed by GPTVis.render(). Supports two formats:

• Syntax format: Markdown-like indentation syntax, suitable for streaming output (renders in real time as the LLM generates tokens)
• JSON format: Standard JSON object, suitable for structured API calls

Both formats are equivalent and can be passed directly to GPTVis.render().

Mode 2: Code Mode

Used when the user needs complete runnable code. Generates output including installation instructions and full code.

GPTVis API

GPTVis is the unified entry class of the library, responsible for creating, rendering, and destroying charts.

Constructor

new GPTVis(options: VisualizationOptions)

VisualizationOptions:

Methods

render(config: string | object): void

Renders a chart. Accepts two kinds of input:

• Syntax string: Text starting with vis [type], automatically parsed into a configuration object
• JSON configuration object: An object containing a type field
• Plain text: Strings not starting with vis are rendered as the summary type

Calling render() multiple times automatically destroys the previous chart before rendering the new one.

destroy(): void

Destroys the current chart instance and releases resources.

Syntax Mode: JSON Format

Directly output a JSON object conforming to the chart's TypeScript type; GPTVis.render() can consume it directly.

JSON Example

{
  "type": "column",
  "data": [
    { "category": "Product A", "value": 30, "group": "Online" },
    { "category": "Product B", "value": 50, "group": "Online" }
  ],
  "title": "Product Sales Comparison",
  "axisXTitle": "Product",
  "axisYTitle": "Sales (10k)",
  "stack": true,
  "theme": "academy",
  "style": {
    "palette": ["#5B8FF9", "#61DDAA"]
  }
}

Syntax Mode: Syntax Format

Markdown-like indentation syntax that supports streaming rendering. The first line must be vis [type].

Syntax Rules

Basic properties — key value, one per line:

title Annual Trend
theme dark

Object arrays — under data, each item starts with - , with sub-fields indented:

{ data: { time: string; value: number; }[]; }

Corresponds to:

data
  - time 2020
    value 100
  - time 2021
    value 120

Plain value arrays — each item starts with - :

{ data: number[] }

Corresponds to:

data
  - 10
  - 20

String values containing spaces — wrap in quotes (single or double); quotes can be omitted when there are no spaces:

categories
  - "North America"
  - 'Southeast Asia'
  - Europe

Nested objects — the object name occupies its own line, with sub-properties indented:

{ style?: { backgroundColor?: string; palette?: string[] } }

Corresponds to:

style
  backgroundColor #f0f2f5
  palette
    - #5B8FF9
    - #61DDAA

Recursive trees — the children array is indented with - :

type TreeData = { name: string; children?: TreeData[] };
{ data: TreeData; }

Corresponds to:

data
  name Root
  children
    - name Child A
      children
        - name Grandchild
    - name Child B

Complete Syntax Example

vis column
data
  - category Product A
    value 30
    group Online
  - category Product B
    value 50
    group Online
title Product Sales Comparison
axisXTitle Product
axisYTitle Sales (10k)
stack true
theme academy
style
  palette
    - #5B8FF9
    - #61DDAA

Markdown Syntax

When the output is in Markdown format, use GPT-Vis as the language tag of the fenced code block, and write the complete Syntax format in the content area:

vis line data

• time 2020

value 100

Format:

<complete Syntax content, first line: vis <chart-type>>

Syntax rules:

• The language tag is fixed as GPT-Vis
• The content area follows the Syntax format rules, and the first line must contain `vis <chart-type>` (see the full list in Supported Chart Types above)
• The code block is converted by the Markdown plugin into <code class="language-gpt-vis"> and rendered on the browser side

Note: In Markdown mode, the content area must include the first line vis <type>, consistent with the plain Syntax mode format.

Code Mode

Generate complete runnable code based on the target framework.

Installation

NPM:

npm install @antv/gpt-vis

import { GPTVis } from '@antv/gpt-vis';

CDN:

<script src="https://unpkg.com/@antv/gpt-vis/dist/umd/index.min.js"></script>

After loading via CDN, access the main class through GPTVis.GPTVis.

Complete HTML Example

<html>
  <head>
    <script src="https://unpkg.com/@antv/gpt-vis/dist/umd/index.min.js"></script>
  </head>
  <body>
    <div id="container"></div>
    <script>
      const gptVis = new GPTVis.GPTVis({
        container: '#container',
        width: 600,
        height: 400,
      });

      gptVis.render(`
vis line
data
  - time 2020
    value 100
  - time 2021
    value 120
title Annual Trend
`);
    </script>
  </body>
</html>

Chart Type Configurations

Common Configuration

All charts include the following fields, which are omitted from the individual chart type definitions below. Each section heading is the type value (e.g. line, column), corresponding to the type column in the chart type table above.

{ type: string; title?: string; theme?: 'default' | 'light' | 'dark' | 'academy'; style?: { backgroundColor?: string; palette?: string[] } }

line / area

{ data: { time: string | number; value: number; group?: string }[]; axisXTitle?: string; axisYTitle?: string; stack?: boolean; style?: { lineWidth?: number } }

stack is only supported by area.

column / bar

{ data: { category: string; value: number; group?: string }[]; axisXTitle?: string; axisYTitle?: string; stack?: boolean; group?: boolean }

pie

Values must not be percentage numbers.

{ data: { category: string; value: number }[]; innerRadius?: number }

Set innerRadius to 0.6 to turn it into a donut chart.

scatter

{ data: { x: number; y: number; group?: string }[]; axisXTitle?: string; axisYTitle?: string }

dual-axes

{ categories: string[]; series: { type: 'line' | 'column'; data: number[]; axisYTitle?: string }[]; axisXTitle?: string; style?: { startAtZero?: boolean } }

histogram

{ data: number[]; binNumber?: number; axisXTitle?: string; axisYTitle?: string }

boxplot / violin

Multiple data points are required for the same category to show distribution.

{ data: { category: string; value: number; group?: string }[]; axisXTitle?: string; axisYTitle?: string; style?: { startAtZero?: boolean } }

radar

{ data: { name: string; value: number; group?: string }[]; align?: boolean }

align: whether to align the scales of all dimensions. Defaults to false (each axis scales independently); when true, all axes share the same maximum value, suitable for comparing absolute values across multiple series.

funnel

{ data: { category: string; value: number; }[]; }

waterfall

Values can be negative to indicate decrease. palette is a color array in the order [positive color, negative color, total color].

{ data: { category: string; value: number }[]; axisXTitle?: string; axisYTitle?: string; style?: { palette?: string[] } }

liquid

percent ranges from 0 to 1.

{ percent: number; shape?: 'rect' | 'circle' | 'pin' | 'triangle' }

word-cloud

{ data: { text: string; value: number; }[]; }

venn

Intersections use commas to separate set identifiers: sets: "A,B". label is used to display the name of the corresponding set on the chart.

{ data: { sets: string | string[]; value: number; label?: string }[] }

treemap

type TreeNode = { name: string; value: number; children?: TreeNode[] };
{ data: TreeNode[] }

sankey

{ data: { source: string; target: string; value: number }[]; nodeAlign?: 'left' | 'center' | 'right' | 'justify' }

flow-diagram / network-graph

source/target reference node name values.

type GraphData = { nodes: { name: string }[]; edges: { source: string; target: string; name?: string }[] };

// flow-diagram
{ data: GraphData }

// network-graph
{ data: GraphData; layout?: 'force' | 'circular' | 'grid' | 'radial' | 'concentric' | 'dagre' }

mindmap / indented-tree / organization-chart

type TreeData = { name: string; children?: TreeData[] };

// mindmap
{ data: TreeData; direction?: 'H' | 'LR' | 'RL' }

// indented-tree
{ data: TreeData; direction?: 'LR' | 'RL' | 'H' }

// organization-chart
type OrganizationChartData = {
  name: string;
  description?: string;
  children?: OrganizationChartData[];
};

{ data: OrganizationChartData }

mindmap defaults to 'H'; indented-tree defaults to 'LR'.

fishbone-diagram

type FishboneNode = { name: string; children?: FishboneNode[] };
{ data: FishboneNode; style?: { texture?: 'rough' | 'default' } }

texture: 'rough' produces a hand-drawn style.

table

{ data: Record<string, string | number>[]; }

summary

summary is completely different from other chart types: it does not use Syntax/JSON configuration, but instead uses T8 syntax (Markdown + semantic annotations).

⚠️ Before generating a summary, you must: first read references/summary.md to get the T8 syntax rules, the complete entity type list, attribute field definitions, generation requirements, and examples, and only then generate the content. Skipping this step will cause syntax errors.

Best Practices

1. Keep pie charts to no more than 5 categories; merge the rest into "Other" or switch to a bar chart
2. Do not use pie charts for trends, and do not use line charts for unordered categories
3. Value fields must be numeric; category fields must be text
4. Distributions of continuous values (e.g. salaries, scores, ages) must use histogram
5. Multi-dimensional field mapping: when there are two categorical dimensions, write the x-axis dimension as time/category and the other as group
6. In Syntax mode, prefer the Syntax format (streaming-friendly)
7. In Code mode, default to the HTML + CDN approach (zero installation); use the npm approach only when the user specifies a framework