Installation

npm install @antv/gpt-vis

🚀 Quick Start

Basic Usage

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

const gptVis = new GPTVis({
  container: 'container',
  width: 600,
  height: 400,
});

// Markdown-like visualization syntax
const visSyntax = `
vis line
data
  - time 2020
    value 100
  - time 2021
    value 120
  - time 2022
    value 150
`;

gptVis.render(visSyntax);

📚 Syntax Guide

render() supports two input formats: vis syntax (ideal for LLM streaming) and JSON objects (ideal for programmatic use).

🔧 Framework Integration

<details> <summary><strong>Vanilla JavaScript</strong></summary>

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

const gptVis = new GPTVis({ container: 'chart', width: 600, height: 400 });
gptVis.render(visSyntaxString);

</details>

<details> <summary><strong>React</strong></summary>

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} />;
}

</details>

<details> <summary><strong>Vue</strong></summary>

<template>
  <div ref="chartRef"></div>
</template>

<script setup>
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());
</script>

</details>

<details> <summary><strong>Markdown Renderer (marked)</strong></summary>

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 `<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
\`\`\`
`;

document.getElementById('content').innerHTML = marked.parse(markdown);

</details>

Base Component

The universal GPTVis component accepts vis syntax strings or config objects for all 26 chart types:

npx shadcn@latest add https://gpt-vis.antv.vision/r/gpt-vis.json

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

<GPTVis
  content="vis line
data
  - time 2020
    value 100
  - time 2021
    value 120
  - time 2022
    value 150
title Sales Trend"
  theme="academy"
/>;

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 https://gpt-vis.antv.vision/r/line.json

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

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

All 26 chart types are available. Install any by name:

```bash npx shadcn@latest add https://gpt-vis.antv.vision/r/pie.json npx shadcn@latest add https://gpt-vis.antv.vision/r/bar.json npx shadcn@latest add https://gpt-vis.antv.vision/r/mindmap.json