Everything you need to know about building AI-powered visualizations with GPT-Vis.
Install GPT-Vis using npm, yarn, or pnpm:
npm install @antv/gpt-visyarn add @antv/gpt-vispnpm add @antv/gpt-visGet started with GPT-Vis in just a few lines of code. Our API is designed to be declarative and intuitive.
import { GPTVis } from '@antv/gpt-vis';
// Create a GPTVis instance
const gptVis = new GPTVis({
container: '#container',
width: 600,
height: 400,
});
// Render with natural syntax
const visSyntax = `
vis line
data
- time 2020
value 100
- time 2021
value 120
- time 2022
value 150
`;
gptVis.render(visSyntax);new GPTVis(options: VisualizationOptions)Creates a new GPTVis instance. Parameters:
gptVis.render(config: string | GPTVisConfig): voidRenders a visualization. Accepts either:
gptVis.destroy(): voidDestroys the GPTVis instance and cleans up all allocated resources.
GPT-Vis natively supports streaming rendering. Since the visualization syntax is line-by-line accumulated plain text, when AI models output token by token, simply pass the received content directly to gptVis.render()— GPT-Vis will skip incomplete syntax fragments and immediately render charts when a complete parsable structure is detected, continuously updating as output progresses, ultimately presenting the complete visualization result.
isVisSyntax(input: any): boolean
Returns true if the input string starts with vis (after trimming). Use this to check whether a streaming buffer has accumulated enough content to attempt rendering.
import { GPTVis, isVisSyntax } from '@antv/gpt-vis';
const gptVis = new GPTVis({
container: '#container',
width: 600,
height: 400
});
let buffer = '';
// Handle streaming tokens
function onToken(token) {
buffer += token;
// Check if we have valid visualization syntax
if (isVisSyntax(buffer)) {
gptVis.render(buffer);
}
}
// Use with your AI model's streaming API
stream.on('token', onToken);Experience streaming rendering in action — type a message below and watch GPT-Vis render charts in real time as the response streams in.
GPT-Vis uses a simple, markdown-like syntax that's easy for LLMs to generate:
vis [chart-type]
[property] [value]
data
- [key] [value]
[nested-key] [nested-value]vis line
title Sales Trend
data
- time 2020
value 100
- time 2021
value 120
- time 2022
value 150
- time 2023
value 180vis pie
data
- category Sales
value 30
- category Marketing
value 25
- category Engineering
value 45
innerRadius 0.6vis bar
data
- category "Product A"
value 120
- category "Product B"
value 95
- category "Product C"
value 150
style
palette
- #691eff
- #8e5aff
- #b58fffvis mindmap
data
- name Project Plan
children
- name Research
children
- name Market Analysis
- name Feasibility Study
- name Developmentvis dual-axes
categories
- "North America"
- "Southeast Asia"
- Europe
series
- type line
name Revenue
data
- 100
- 120
- 90
- type column
name Units
data
- 50
- 60
- 45As an alternative to the string syntax, render() also accepts a plain JavaScript / JSON object directly. The object must include a type field matching the chart type identifier. This is useful when the config is already structured in code or returned by an API.
gptVis.render({
type: 'line',
title: 'Sales Trend',
data: [
{ time: '2020', value: 100 },
{ time: '2021', value: 120 },
{ time: '2022', value: 150 },
{ time: '2023', value: 180 },
],
});gptVis.render({
type: 'pie',
innerRadius: 0.6,
data: [
{ category: 'Sales', value: 30 },
{ category: 'Marketing', value: 25 },
{ category: 'Engineering', value: 45 },
],
});gptVis.render({
type: 'bar',
data: [
{ category: 'Product A', value: 120 },
{ category: 'Product B', value: 95 },
{ category: 'Product C', value: 150 },
],
style: {
palette: ['#691eff', '#8e5aff', '#b58fff'],
},
});GPT-Vis provides 26 chart types optimized for AI generation. Each component is designed with an editorial aesthetic first.
Time series and trend visualization
Compare categorical data
Filled line charts for volume
Part-to-whole relationships
Correlation and distribution
Multi-dimensional comparison
Vertical bar comparisons
Process flow visualization
Sequential value changes
Statistical distribution
Distribution density
Frequency distribution
Flow and transition
Hierarchical data
Set relationships
Structured data display
Two y-axes for mixed data series
Percentage fill gauge visualization
Text frequency visualization
AI-generated text summary card
Process and workflow visualization
Hierarchical tree with indentation
Radial mind map visualization
Node-link network relationships
Org hierarchy visualization
Cause-and-effect root cause analysis
GPT-Vis provides three built-in themes: default, dark, academy. Set the theme field in vis syntax or JSON config to apply a theme globally to the chart.
default
vis column
theme default
...dark
vis column
theme dark
...academy
vis column
theme academy
...Override the default color palette by setting style.palette with an array of hex colors. Colors are assigned to data series in order.
vis bar
data
- category Design
value 30
- category Engineering
value 45
- category Marketing
value 25
- category Sales
value 38
style
palette
- #691eff
- #8e5aff
- #b58fff
- #d4b0ffGPT-Vis ships a chart-visualization skill for AI agents (e.g. Claude Code). Copy the skill file into your project to enable automatic chart type selection and GPT-Vis syntax generation from natural language.
Installation
npx skills add https://github.com/antvis/GPT-VisUsage Examples
Show monthly sales from Jan to Jun as a line chart, output vis syntaxShow market share breakdown as a pie chart, output JSON configCreate a bar chart comparing Q1–Q4 revenue, give me a complete HTML fileBuild a React component that renders a scatter plot of height vs weightFollow these guidelines to get the best results when integrating GPT-Vis with AI agents.
GPT-Vis uses a markdown-like code fence syntax (vis <type>) that naturally integrates with any Markdown renderer. By customizing the code block renderer, you can turn vis fenced blocks into interactive charts while keeping normal code blocks syntax-highlighted. Below is an example using marked.
Integrate GPT-Vis into marked with marked-highlight. Normal code blocks get syntax highlighting via highlight.js, while vis code blocks are rendered as interactive charts.
Installation
npm install @antv/gpt-vis marked marked-highlight highlight.jsUse marked-highlight for syntax highlighting, and override renderer.code to render vis code blocks as GPT-Vis charts:
import { Marked } from 'marked';
import { markedHighlight } from 'marked-highlight';
import hljs from 'highlight.js';
import { GPTVis } from '@antv/gpt-vis';
class GPTVisElement extends HTMLElement {
connectedCallback() {
const syntax = decodeURIComponent(this.dataset.syntax);
this._instance = new GPTVis({ container: this });
this._instance.render(syntax);
}
disconnectedCallback() {
this._instance?.destroy();
}
}
if (!customElements.get('gpt-vis')) {
customElements.define('gpt-vis', GPTVisElement);
}
const marked = new Marked(
markedHighlight({
langPrefix: 'hljs language-',
highlight(code, lang) {
if (lang?.startsWith('vis')) return code;
const language = hljs.getLanguage(lang) ? lang : 'plaintext';
return hljs.highlight(code, { language }).value;
},
}),
{
renderer: {
code({ text, lang }) {
if (lang?.startsWith('vis')) {
const syntax = encodeURIComponent(lang + '\n' + text);
return `<gpt-vis data-syntax="${syntax}" style="min-height:300px"></gpt-vis>`;
}
return false;
},
},
},
);
const markdown = `# My Report
```vis bar
data
- category Python
value 28.1
- category JavaScript
value 18.5
- category Java
value 15.6
- category "C/C++"
value 12.3
title 2024 Programming Language Popularity
```
```javascript
// Normal code blocks get syntax highlighting
const gptVis = new GPTVis({ container: el });
gptVis.render(visSyntax);
```
`;
document.getElementById('content').innerHTML = marked.parse(markdown);In React, you can create an instance in useEffect and mount it to a ref:
import { GPTVis } from '@antv/gpt-vis';
import { useEffect, useRef } from 'react';
function ChartComponent({ visSyntax }) {
const containerRef = useRef();
const gptVisRef = useRef();
useEffect(() => {
gptVisRef.current = new GPTVis({
container: containerRef.current,
width: 600,
height: 400
});
return () => gptVisRef.current?.destroy();
}, []);
useEffect(() => {
if (gptVisRef.current && visSyntax) {
gptVisRef.current.render(visSyntax);
}
}, [visSyntax]);
return <div ref={containerRef} />;
}In Vue 3, you can create an instance in the onMounted lifecycle hook and mount it to a ref:
<template>
<div ref="chartRef"></div>
</template>
<script setup>
import { ref, onMounted, onUnmounted, watch } from 'vue';
import { GPTVis } from '@antv/gpt-vis';
const props = defineProps(['visSyntax']);
const chartRef = ref(null);
let gptVis = null;
onMounted(() => {
gptVis = new GPTVis({
container: chartRef.value,
width: 600,
height: 400
});
gptVis.render(props.visSyntax);
});
watch(
() => props.visSyntax,
(newSyntax) => {
if (gptVis) gptVis.render(newSyntax);
}
);
onUnmounted(() => gptVis?.destroy());
</script>