Documentation

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

Installation

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

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

Quick Start

Get started with GPT-Vis in just a few lines of code:

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

That's it! You've created your first AI-friendly chart.

GPTVis API

Constructor

new GPTVis(config: GPTVisConfig)

Creates a new GPTVis instance.

Parameters:

  • container: string | HTMLElement - Container element or selector
  • width: number - Chart width in pixels
  • height: number - Chart height in pixels

render()

gptVis.render(syntax: string): void

Renders a visualization from syntax string.

Parameters:

  • syntax: string - Visualization syntax to render

destroy()

gptVis.destroy(): void

Destroys the GPTVis instance and cleans up resources.

Streaming Support

GPT-Vis supports real-time rendering of streaming data from AI models:

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

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]

Line Chart Example

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

Pie Chart Example

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

Components

GPT-Vis provides 20+ chart types optimized for AI generation:

📈

Line

Time series and trend visualization

📊

Bar

Compare categorical data

🌊

Area

Filled line charts for volume

🥧

Pie

Part-to-whole relationships

⚫

Scatter

Correlation and distribution

🎯

Radar

Multi-dimensional comparison

📊

Column

Vertical bar comparisons

🔻

Funnel

Process flow visualization

🌊

Waterfall

Sequential value changes

📦

Boxplot

Statistical distribution

🎻

Violin

Distribution density

📊

Histogram

Frequency distribution

🌀

Sankey

Flow and transition

🗺️

Treemap

Hierarchical data

⭕

Venn

Set relationships

📋

Table

Structured data display

AI Agent Integration

Integrate GPT-Vis with your AI agents for automatic visualization generation:

🤖 OpenAI Integration

import OpenAI from 'openai';
import { GPTVis, isVisSyntax } from '@antv/gpt-vis';

const openai = new OpenAI();
const gptVis = new GPTVis({ container: '#chart' });

const stream = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{
    role: 'user',
    content: 'Show sales trend for 2020-2023'
  }],
  stream: true,
});

let buffer = '';
for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content || '';
  buffer += content;
  if (isVisSyntax(buffer)) {
    gptVis.render(buffer);
  }
}

💡 Best Practices

  • Use the isVisSyntax() helper to detect valid syntax
  • Include GPT-Vis syntax examples in your system prompts
  • Leverage the knowledge base for chart type selection
  • Handle incomplete syntax gracefully during streaming

Framework Integration

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

🟢 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>
← Back to HomeView Examples →