ai-ez-chart

Simple, powerful chart generation with QuickChart.io - optimized for AI agent integration.

Features

• Auto data transformation - Pass arrays, objects, CSV - it just works
• Smart chart selection - Automatically picks the best chart type based on your data and intent
• Multiple output formats - PNG, SVG, JPG, WebP
• 6 style presets - minimal, business, dark, vibrant, accessible, print
• Custom API endpoint - Use QuickChart.io or self-hosted instance
• AI-optimized - Designed for seamless AI agent integration
• Zero dependencies (except zod for validation)

Installation

npm install ai-ez-chart

Quick Start

import { createEZChart } from 'ai-ez-chart';

const chart = createEZChart();

// Simple API - just data and intent
const result = await chart.simple({
  data: { 'Q1': 100, 'Q2': 150, 'Q3': 120, 'Q4': 200 },
  intent: 'trend',
  title: 'Quarterly Revenue',
  style: 'business',
});

console.log(result.url);
// https://quickchart.io/chart?c=...

API

Simple API

Best for AI agents - just provide data and intent:

const result = await chart.simple({
  data: { 'Jan': 100, 'Feb': 150, 'Mar': 120 },
  intent: 'trend',      // compare | trend | distribution | composition | relationship | progress
  title: 'Monthly Sales',
  style: 'minimal',     // minimal | business | dark | vibrant | accessible | print
  output: {
    format: 'png',      // png | svg | jpg | webp
    width: 800,
    height: 600,
  },
});

Structured API

More control over chart configuration:

const result = await chart.create({
  type: 'bar',          // Explicit chart type
  data: [
    { label: 'Product A', value: 30 },
    { label: 'Product B', value: 45 },
  ],
  style: 'vibrant',
  title: 'Sales by Product',
});

Get Base64

For embedding in HTML/emails:

const result = await chart.toBase64({
  data: [10, 20, 30],
  intent: 'compare',
});

const img = `<img src="data:image/png;base64,${result.base64}" />`;

Get Buffer

For saving to file:

import { writeFileSync } from 'fs';

const result = await chart.toBuffer({
  data: { A: 10, B: 20, C: 30 },
  intent: 'composition',
  output: { format: 'jpg' },
});

writeFileSync('chart.jpg', result.buffer);

Analyze Data

Get chart recommendations:

const analysis = chart.analyze({
  'Jan': 100, 'Feb': 120, 'Mar': 90, 'Apr': 150,
});

console.log(analysis.recommended);
// { type: 'line', reasoning: '...', confidence: 0.85 }

Get URL Only

Synchronous, no fetch:

const url = chart.getUrl({
  data: [1, 2, 3],
  intent: 'compare',
});

Custom Base URL

Use self-hosted QuickChart or alternative API:

// Option 1: Set in constructor
const chart = createEZChart({
  baseUrl: 'https://your-quickchart-server.com/chart'
});

// Option 2: Set after creation
const chart = createEZChart();
chart.setBaseUrl('https://your-quickchart-server.com/chart');

// Get current base URL
console.log(chart.getBaseUrl());

Supported Data Formats

ai-ez-chart automatically detects and transforms these formats:

// 1. Number array
[10, 20, 30]

// 2. Key-value object
{ 'Q1': 100, 'Q2': 150, 'Q3': 120 }

// 3. Label-value array
[{ label: 'A', value: 10 }, { label: 'B', value: 20 }]

// 4. Multi-series object
{ sales: [100, 150, 120], costs: [80, 90, 100] }

// 5. Standard ChartData
{ labels: ['A', 'B'], datasets: [{ data: [10, 20] }] }

// 6. CSV string
'Category,Sales,Costs\nNorth,100,80\nSouth,150,90'

Chart Types

| Type | Best For | |------|----------| | bar | Comparing categories | | horizontalBar | Long labels, rankings | | line | Trends over time | | area | Trends with volume | | pie | Part of whole (≤7 items) | | doughnut | Part of whole (modern) | | radar | Multi-dimensional comparison | | scatter | Relationships between variables | | polarArea | Cyclic data |

Intents

| Intent | Auto-selects | |--------|--------------| | compare | bar, horizontalBar | | trend | line, area | | distribution | bar, scatter | | composition | pie, doughnut | | relationship | scatter, bubble | | progress | radialGauge, progressBar |

Style Presets

| Preset | Description | |--------|-------------| | minimal | Clean, modern (default) | | business | Professional with data labels | | dark | Dark theme | | vibrant | Colorful | | accessible | High contrast, WCAG friendly | | print | Print-optimized |

Output Formats

• PNG - Default, best for web
• SVG - Scalable, best for print/zoom
• JPG - Smaller file size, no transparency
• WebP - Modern format, best compression

Error Handling

const result = await chart.simple({
  data: { A: -10, B: 20 },
  intent: 'composition',  // pie chart
});

if (!result.success) {
  console.log(result.errors);
  // [{ field: 'data', message: 'Pie cannot display negative values', ... }]
}

TypeScript

Full TypeScript support with exported types:

import type {
  ChartType,
  ChartIntent,
  StylePreset,
  OutputFormat,
  ChartResult,
  SimpleRequest,
  StructuredRequest,
  DataAnalysis,
  EZChartOptions,
} from 'ai-ez-chart';

License

MIT