gpt-vis

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
• 🎨 Theme System — Built-in light, dark, and academy themes with customizable color palettes

🚀 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	#1783FF #F08F56 #D580FF #00C9C9 #7863FF ...
Dark	dark	#000	#1783FF #F08F56 #D580FF #00C9C9 #7863FF ...
Academy	academy	#FFF	#4e79a7 #f28e2c #e15759 #76b7b2 #59a14f ...

gptVis.render({
  type: 'line',
  data: [
    { time: '2020', value: 100 },
    { time: '2021', value: 120 },
  ],
  theme: 'dark',
});

Custom Styles:

gptVis.render({
  type: 'line',
  data: [
    { time: '2020', value: 100 },
    { time: '2021', value: 120 },
  ],
  style: { 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
  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 — Provide AI assistants with chart recommendation and generation capabilities, supporting both syntax mode and code mode output

🤝 Contributing

AI-Generated Code Policy: This project only merges AI-generated code.

1. Submit an Issue describing the problem or feature request
2. Tag @copilot to generate the implementation
3. Submit a PR with AI-generated code

📄 License

MIT © AntV