English | 简体中文
GPT-Vis
AI-native visualization library for the LLM era. Framework-agnostic, ready to use.
📖 Documentation ·
🎨 Examples ·
🔌 MCP Server ·
🧩 Chart Skill
✨ Features
- 🚀 Framework Agnostic — Works with vanilla JavaScript, React, Vue, Angular, or any framework
- ✍️ Markdown-like Syntax — Simple syntax that LLMs can generate directly, easy to learn and use
- 🌊 Streaming Rendering — Native support for AI model streaming output, renders as it generates
- 🛡️ Fault Tolerant — Gracefully handles incomplete or malformed data, adapts to the uncertainty of AI-generated content
- 📊 26 Chart Types — Statistical charts, relationship graphs, and text visualizations covering mainstream scenarios
- 🎨 Reusable Themes — Share one ThemeSpec across all chart types; preview and refine it in Theme Studio, or create it with an AI skill
🚀 Quick Start
Installation
npm install @antv/gpt-vis
Basic Usage
import { GPTVis } from '@antv/gpt-vis';
const gptVis = new GPTVis({
container: 'container',
width: 600,
height: 400,
});
gptVis.render({
type: 'line',
data: [
{ time: '2020', value: 100 },
{ time: '2021', value: 120 },
{ time: '2022', value: 150 },
],
});
Streaming Rendering
Charts render as the AI model generates, no need to wait for the full response:
import { GPTVis, isVisSyntax } from '@antv/gpt-vis';
const gptVis = new GPTVis({ container: 'container', width: 600, height: 400 });
let buffer = '';
function onToken(token) {
buffer += token;
if (isVisSyntax(buffer)) {
gptVis.render(buffer);
}
}
📚 Syntax Guide
render() supports two input formats: JSON objects (ideal for programmatic use) and DSL syntax (ideal for LLM streaming).
Object Config
Pass JSON objects directly for programmatic chart creation:
Line chart:
gptVis.render({
type: 'line',
data: [
{ time: '2020', value: 100 },
{ time: '2021', value: 120 },
{ time: '2022', value: 150 },
],
});
Pie chart:
gptVis.render({
type: 'pie',
data: [
{ category: 'Android', value: 72 },
{ category: 'iOS', value: 28 },
],
innerRadius: 0.6,
});
Themes:
Three built-in themes, switchable via the theme property:
| Theme | Identifier | Background | Palette |
|---|
| Default (Light) | default | #FFF | #5B6CFF #2DAF9E #F2B84B #EF6A6A #55A6D9 ... |
| Dark | dark | #141414 | #5B6CFF #2DAF9E #F2B84B #EF6A6A #55A6D9 ... |
| Academy | academy | #FFF | #4e79a7 #f28e2c #e15759 #76b7b2 #59a14f ... |
gptVis.render({
type: 'line',
data: [
{ time: '2020', value: 100 },
{ time: '2021', value: 120 },
],
theme: 'dark',
});
Reusable custom themes:
Pass a ThemeSpec object to the constructor's theme option to share colors, typography, spacing, and mark styles across all 26 chart types, including graphs, Table, and Summary:
import { GPTVis, type ThemeSpec } from '@antv/gpt-vis';
const theme: ThemeSpec = {
id: 'my-report',
label: 'My report',
tokens: { colorDefault: '#7047eb', fontFamily: 'Arial, sans-serif', radius: 6 },
};
const chart = new GPTVis({ container: '#chart', theme });
Precedence: single-chart config > custom ThemeSpec > GPT-Vis built-in theme. Within this hierarchy: built-in defaults < tokens < global style < charts[type].style < local style. Nested objects merge; arrays replace. A chart-level theme replaces the constructor's theme selection. Summary uses a constructor theme and T8 text, without a per-render style object.
Explore Theme Studio, read the theme documentation, or use the theme creation guide to generate a ThemeSpec from your brand references.
Studio presets are ThemeSpec examples. Pass the object as theme; its id is metadata, not a registered theme name.
Custom Styles:
gptVis.render({
type: 'line',
data: [
{ time: '2020', value: 100 },
{ time: '2021', value: 120 },
],
style: { mark: { line: { lineWidth: 3 } }, palette: ['#5B8FF9', '#5AD8A6'] },
});
DSL Syntax
Declarative markdown-like syntax that LLMs can generate without learning complex APIs:
vis [chart-type]
[property] [value]
data
- [field] [value]
Pie chart:
vis pie
data
- category Sales
value 30
- category Marketing
value 25
innerRadius 0.6
Themes:
vis line
data
- time 2020
value 100
- time 2021
value 120
theme dark
Custom Styles:
Use style to set line width, custom palettes, and more:
vis line
data
- time 2020
value 100
- time 2021
value 120
style
mark
line
lineWidth 3
palette
- #5B8FF9
- #5AD8A6
Quoted string values (for values with spaces):
vis pie
data
- category "Q1 Sales"
value 30
- category "Q2 Sales"
value 25
Hierarchical data:
vis mindmap
data
- name Project Plan
children
- name Phase 1
- name Phase 2
Render DSL syntax:
const visSyntax = `
vis line
data
- time 2020
value 100
- time 2021
value 120
- time 2022
value 150
`;
gptVis.render(visSyntax);
📊 Chart Types
26 chart types covering statistical analysis, relationship networks, and text visualization.
Statistical Charts (18)
| Chart | Type Identifier |
|---|
| Line | line |
| Area | area |
| Column | column |
| Bar | bar |
| Pie | pie |
| Scatter | scatter |
| Radar | radar |
| Funnel | funnel |
| Waterfall | waterfall |
| Dual Axes | dual-axes |
| Histogram | histogram |
| Boxplot | boxplot |
| Violin | violin |
| Venn | venn |
| Sankey | sankey |
| Treemap | treemap |
| Word Cloud | word-cloud |
| Liquid | liquid |
Relationship Charts (6)
| Chart | Type Identifier |
|---|
| Flow Diagram | flow-diagram |
| Network Graph | network-graph |
| Mindmap | mindmap |
| Indented Tree | indented-tree |
| Organization Chart | organization-chart |
| Fishbone Diagram | fishbone-diagram |
Text Visualization (2)
| Chart | Type Identifier |
|---|
| Table | table |
| Summary | summary |
Explore all examples → Examples Gallery
🔧 Framework Integration
Vanilla JavaScript
import { GPTVis } from '@antv/gpt-vis';
const gptVis = new GPTVis({ container: 'chart', width: 600, height: 400 });
gptVis.render(visSyntaxString);
React
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 ;
}
Vue
import { ref, watch, onUnmounted } from 'vue';
import { GPTVis } from '@antv/gpt-vis';
const props = defineProps(['visSyntax']);
const chartRef = ref(null);
let gptVis = null;
watch(
() => props.visSyntax,
(syntax) => {
if (!gptVis) {
gptVis = new GPTVis({ container: chartRef.value, width: 600, height: 400 });
}
gptVis.render(syntax);
},
{ immediate: true },
);
onUnmounted(() => gptVis?.destroy());
Markdown Renderer (marked)
GPT-Vis syntax naturally works with Markdown code fences and integrates with any Markdown renderer. The following example uses marked + marked-highlight — normal code blocks get syntax highlighting, while vis code blocks are rendered as interactive charts.
Install dependencies:
npm install @antv/gpt-vis marked marked-highlight highlight.js
Complete example:
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 ``;
}
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
\`\`\`
`;
document.getElementById('content').innerHTML = marked.parse(markdown);
🧩 Shadcn/ui
Copy GPT-Vis React components directly into your project via shadcn CLI — full source control, fully customizable.
Base Component
The universal GPTVis component accepts vis syntax strings or config objects for all 26 chart types:
npx shadcn@latest add @gpt-vis/gpt-vis
import { GPTVis } from '@/components/ui/gpt-vis';
;
Typed Chart Components
Each chart type has its own component with a typed config prop — JSON only, chart-specific TypeScript validation:
npx shadcn@latest add @gpt-vis/line
import { Line } from '@/components/ui/line';
;
All 26 chart types are available. Install any by name:
npx shadcn@latest add @gpt-vis/pie
npx shadcn@latest add @gpt-vis/bar
npx shadcn@latest add @gpt-vis/mindmap
# ...and more
Each typed component automatically bundles the base GPTVis component as a dependency. Props like width, height, theme, wrapper, locale, className, and containerStyle are the same across all components.
🤖 AI Ecosystem
GPT-Vis provides a complete AI integration solution:
- MCP Server — Enable AI models to directly invoke visualization capabilities via Model Context Protocol
- Chart Skill — Help AI assistants choose charts, generate JSON, Syntax or integration code, and create reusable themes with the bundled Theme Creator reference
🤝 Contributing
AI-Generated Code Policy: This project only merges AI-generated code.
- Submit an Issue describing the problem or feature request
- Tag @copilot to generate the implementation
- Submit a PR with AI-generated code
📄 License
MIT © AntV
