Documentation

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

npm install @antv/gpt-vis

yarn add @antv/gpt-vis

pnpm add @antv/gpt-vis

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

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.

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.

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]

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

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

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

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

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

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.

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.

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.

vis column
theme default
...

vis column
theme dark
...

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

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.

npm install @antv/gpt-vis marked marked-highlight highlight.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);

Use npx shadcn@latest add to copy GPT-Vis React components into your project. Two options: the base component (accepts any chart via vis syntax or config objects), or typed individual components for each chart type with dedicated config props.

Base Component

The gpt-vis component is the universal wrapper — render any of 26 chart types by passing a vis syntax string or config object to content. Ideal for LLM-generated visualizations and streaming.

Installing

npx shadcn@latest add @gpt-vis/gpt-vis

This copies the component into src/components/ui/gpt-vis.tsx.

Usage

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

const visSyntax = `vis line
data
  - time 2020
    value 100
  - time 2021
    value 120
  - time 2022
    value 150
title Sales Trend`;

export default function MyChart() {
  return <GPTVis content={visSyntax} theme="academy" />;
}

Props

Typed Chart Components

Each of the 26 chart types has its own shadcn component with a typed config prop — the chart-specific config object without the type field. Every component bundles the base gpt-vis as a dependency, so you get both files installed automatically.

Installing

Install any chart component by name. The base component is automatically included:

npx shadcn@latest add @gpt-vis/line

This installs both line.tsx and gpt-vis.tsx into src/components/ui/.

Usage

Import the typed component and pass a config object. The type field is auto-filled, and TypeScript validates the data shape specific to that chart:

import { Line } from '@/components/ui/line';

export default function MyChart() {
  return (
    <Line
      config={{
        data: [
          { time: '2020', value: 100 },
          { time: '2021', value: 120 },
          { time: '2022', value: 150 },
        ],
        title: 'Sales Trend',
        axisXTitle: 'Year',
      }}
      height={400}
    />
  );
}

Config vs Content

The key difference: typed components use config (JSON only, chart-specific types) instead of content (string or object). All other props (width, height, theme, wrapper, locale, className, containerStyle) pass through directly.

// Base component — content: anything
<GPTVis content="vis line ..." />
<GPTVis content={{ type: 'pie', data: [...] }} />

// Typed components — config: chart-specific, no type field
<Line config={{ data: [{ time, value }], title: '...' }} />
<Pie config={{ data: [{ category, value }], innerRadius: 0.6 }} />
<Bar config={{ data: [{ category, value }], stack: true }} />
<Sankey config={{ data: [{ source, target, value }] }} />
<Mindmap config={{ data: { name: 'root', children: [...] } }} />

All 26 Chart Types

Install name pattern: @gpt-vis/<type>

We are continuously expanding the GPT-Vis ecosystem. From editor integrations and framework bindings to AI toolchains and beyond—whatever you can imagine can be part of it. We welcome community contributors to bring new ideas and projects, and help us grow the map together.