Documentation

Everything you need to know about building AI-powered visualizations with GPT-Vis.

Installation#

Install GPT-Vis using npm, yarn, or pnpm:

npm
npm install @antv/gpt-vis
yarn
yarn add @antv/gpt-vis
pnpm
pnpm add @antv/gpt-vis

Quick Start#

Get 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);

GPTVis API#

Constructor

new GPTVis(options: VisualizationOptions)

Creates a new GPTVis instance. Parameters:

  • container: string | HTMLElement — container element or CSS selector (required)
  • width?: number — chart width in pixels (optional)
  • height?: number — chart height in pixels (optional)
  • theme?: 'default' | 'light' | 'dark' | 'academy' — visualization theme (optional)
  • wrapper?: boolean — enable wrapper UI with tabs, download and copy controls (default: false)
  • locale?: string — locale for wrapper labels (default: 'zh-CN')

render()

gptVis.render(config: string | GPTVisConfig): void

Renders a visualization. Accepts either:

  • A string — GPT-Vis markdown-like syntax starting with vis [chart-type] · Syntax Guide →
  • A GPTVisConfig object — plain config object with a type field and chart data · JSON Config →

destroy()

gptVis.destroy(): void

Destroys the GPTVis instance and cleans up all allocated resources.

Streaming Support#

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);

Try it out

Experience streaming rendering in action — type a message below and watch GPT-Vis render charts in real time as the response streams in.

G
Hello! I'm ready to visualize your data. Try asking me to generate a chart, and you'll see it stream in real-time.
Draw a

Visualization Syntax#

GPT-Vis uses a simple, markdown-like syntax that's easy for LLMs to generate:

Basic Structure
vis [chart-type]
[property] [value]
data
  - [key] [value]
    [nested-key] [nested-value]

Syntax Rules

  • First line must be vis [chart-type]
  • Top-level key-value pairs use either key value or key: value format
  • data, categories, series, nodes, edges sections use dash-prefixed array items (- key value)
  • Values containing spaces must be quoted: "North America" or 'North America' (quoted values are never coerced to numbers or booleans)
  • children inside a data item creates nested hierarchical data (used by mindmap, treemap, fishbone-diagram, etc.)
  • style section accepts key-value pairs and a palette array

Line Chart

vis line
title Sales Trend
data
  - time 2020
    value 100
  - time 2021
    value 120
  - time 2022
    value 150
  - time 2023
    value 180

Pie Chart

vis pie
data
  - category Sales
    value 30
  - category Marketing
    value 25
  - category Engineering
    value 45
innerRadius 0.6

Bar Chart with Style

vis bar
data
  - category "Product A"
    value 120
  - category "Product B"
    value 95
  - category "Product C"
    value 150
style
  palette
    - #691eff
    - #8e5aff
    - #b58fff

Hierarchical Data (Mindmap)

vis mindmap
data
  - name Project Plan
    children
      - name Research
        children
          - name Market Analysis
          - name Feasibility Study
      - name Development

Quoted String Values (Dual Axes)

vis dual-axes
categories
  - "North America"
  - "Southeast Asia"
  - Europe
series
  - type line
    name Revenue
    data
      - 100
      - 120
      - 90
  - type column
    name Units
    data
      - 50
      - 60
      - 45

JSON Config Syntax

As 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.

Line Chart

gptVis.render({
  type: 'line',
  title: 'Sales Trend',
  data: [
    { time: '2020', value: 100 },
    { time: '2021', value: 120 },
    { time: '2022', value: 150 },
    { time: '2023', value: 180 },
  ],
});

Pie Chart

gptVis.render({
  type: 'pie',
  innerRadius: 0.6,
  data: [
    { category: 'Sales', value: 30 },
    { category: 'Marketing', value: 25 },
    { category: 'Engineering', value: 45 },
  ],
});

Bar Chart with Style

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'],
  },
});

Components#

GPT-Vis provides 26 chart types optimized for AI generation. Each component is designed with an editorial aesthetic first.

Style Configuration#

Built-in Themes

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
...

Custom Palette

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
    - #d4b0ff

AI Agent Integration#

Chart Visualization Skill

GPT-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

bash
npx skills add https://github.com/antvis/GPT-Vis

Usage Examples

Generate vis syntax
Show monthly sales from Jan to Jun as a line chart, output vis syntax
Generate JSON config
Show market share breakdown as a pie chart, output JSON config
Generate full HTML
Create a bar chart comparing Q1–Q4 revenue, give me a complete HTML file
Generate React component
Build a React component that renders a scatter plot of height vs weight

Best Practices

Follow these guidelines to get the best results when integrating GPT-Vis with AI agents.

  • Use the chart-visualization skill to handle chart type selection and syntax generation automatically
  • Use isVisSyntax() to detect valid syntax before calling render() in streaming scenarios
  • Handle incomplete syntax gracefully during streaming — render() is designed to be called repeatedly as tokens arrive
  • Prefer vis syntax format for streaming output; use JSON config for structured API responses

Markdown Integration#

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.

Using with 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

bash
npm install @antv/gpt-vis marked marked-highlight highlight.js

Complete Example

Use marked-highlight for syntax highlighting, and override renderer.code to render vis code blocks as GPT-Vis charts:

js
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);

Framework Integration#

Using in React

In React, you can create an instance in useEffect and mount it to a ref:

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 <div ref={containerRef} />;
}

Using in Vue

In Vue 3, you can create an instance in the onMounted lifecycle hook and mount it to a ref:

Vue
<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>