@json-render-plugins/echarts

ECharts component library for @json-render/core. Transform JSON specifications into beautiful ECharts visualizations using SVG rendering.

Features

• Six Chart Types: LineChart, PieChart, BarChart, RadarChart, ScatterChart, BoxplotChart
• SVG Rendering: High-quality vector graphics for all charts
• Full Customization: Comprehensive props for styling and behavior
• Type-Safe: Full TypeScript support with Zod schemas
• React Integration: Seamless integration with @json-render/react

Installation

npm install @json-render-plugins/echarts echarts react react-dom
# or
pnpm add @json-render-plugins/echarts echarts react react-dom
# or
yarn add @json-render-plugins/echarts echarts react react-dom

Quick Start

1. Create a Catalog

Import standard definitions from @json-render-plugins/echarts/catalog:

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";
import { echartsComponentDefinitions } from "@json-render-plugins/echarts/catalog";

const catalog = defineCatalog(schema, {
  components: {
    LineChart: echartsComponentDefinitions.LineChart,
    PieChart: echartsComponentDefinitions.PieChart,
    BarChart: echartsComponentDefinitions.BarChart,
    RadarChart: echartsComponentDefinitions.RadarChart,
    ScatterChart: echartsComponentDefinitions.ScatterChart,
    BoxplotChart: echartsComponentDefinitions.BoxplotChart,
  },
  actions: {},
});

2. Create a Registry

Import implementations from @json-render-plugins/echarts:

import { defineRegistry } from "@json-render/react";
import { echartsComponents } from "@json-render-plugins/echarts";

const { registry } = defineRegistry(catalog, {
  components: {
    LineChart: echartsComponents.LineChart,
    PieChart: echartsComponents.PieChart,
    BarChart: echartsComponents.BarChart,
    RadarChart: echartsComponents.RadarChart,
    ScatterChart: echartsComponents.ScatterChart,
    BoxplotChart: echartsComponents.BoxplotChart,
  },
});

3. Render

import { Renderer } from "@json-render/react";

function App({ spec }) {
  return <Renderer spec={spec} registry={registry} />;
}

Components

LineChart

Line charts display data trends over time or categories. Supports area fills, stacking, smooth curves, and symbol customization. Multiple series can share the same coordinate system. Use smooth=true for curved lines, areaStyle=true for filled regions. Customize symbols, line styles, and item styles for visual distinction.

{
  "type": "LineChart",
  "props": {
    "xAxisData": ["Jan", "Feb", "Mar", "Apr", "May"],
    "series": [
      {
        "name": "Revenue",
        "data": [120, 200, 150, 80, 70],
        "smooth": true,
        "areaStyle": true
      },
      {
        "name": "Cost",
        "data": [80, 100, 120, 60, 50]
      }
    ],
    "title": "Financial Overview",
    "showTooltip": true,
    "showLegend": true
  }
}

Key Props:

• xAxisData: Array of X-axis labels
• series: Array of line series with name, data, and optional styling
• smooth: Enable smooth curves
• areaStyle: Fill area under line
• symbol: Point marker shape (circle, rect, triangle, etc.)
• lineStyle: Line style with width and type (solid, dashed, dotted)

PieChart

Pie and donut charts showing data proportions and percentages. Use radius property with [inner, outer] to create donut charts. Supports Nightingale rose charts via pieType='rose' with 'radius' mode (central angle shows percentage, radius shows size) or 'area' mode (same angle, radius shows size). Labels can be positioned outside (connected via visual guide line), inside/inner (within sectors), or center. Enable selectedMode for interactive selection.

{
  "type": "PieChart",
  "props": {
    "data": [
      { "name": "Category A", "value": 335 },
      { "name": "Category B", "value": 310 },
      { "name": "Category C", "value": 234 }
    ],
    "title": "Market Share",
    "radius": ["40%", "70%"],
    "showLabel": true,
    "showTooltip": true
  }
}

Key Props:

• data: Array of slices with name, value, and optional color
• radius: Single value or [inner, outer] for donut charts
• pieType: Set to "rose" for rose chart
• selectedMode: Enable selection ("single" or "multiple")
• labelPosition: Label position - "outside", "inside", "center"

BarChart

Bar charts featuring stacked series, background bars, and custom styling. Supports stacking multiple series with stack property, custom bar widths, rounded corners via itemStyle.borderRadius, and background bars with showBackground and backgroundStyle. Use horizontal=true for horizontal bars. Multiple series can share the same coordinate system for effective comparison across categories.

{
  "type": "BarChart",
  "props": {
    "xAxisData": ["Product A", "Product B", "Product C"],
    "series": [
      { "name": "Sales", "data": [320, 332, 301] },
      { "name": "Marketing", "data": [120, 132, 101], "stack": "total" }
    ],
    "title": "Product Performance",
    "showTooltip": true,
    "horizontal": false
  }
}

Key Props:

• xAxisData: Array of X-axis labels
• series: Array of bar series with name, data, and optional styling
• horizontal: Flip axes for horizontal bars
• stack: Group name for stacked bars
• barWidth: Control bar width

RadarChart

Radar charts display multi-dimensional data on a spider/web coordinate system where each axis represents one dimension. Ideal for performance analysis, skill assessment, and KPI dashboards.

{
  "type": "RadarChart",
  "props": {
    "indicator": [
      { "name": "Speed", "max": 100 },
      { "name": "Strength", "max": 100 },
      { "name": "Agility", "max": 100 },
      { "name": "Intelligence", "max": 100 },
      { "name": "Stamina", "max": 100 }
    ],
    "data": [
      { "name": "Player A", "value": [80, 70, 90, 60, 75], "areaStyle": {} },
      { "name": "Player B", "value": [65, 85, 55, 80, 70] }
    ],
    "title": "Player Comparison"
  }
}

Key Props:

• indicator: Array of axes with name and optional max
• data: Array of { name, value: number[], color?, areaStyle? }
• series: Alternative data format { name, data: number[], color?, areaStyle? }
• shape: "polygon" (default) or "circle"
• splitNumber: Number of split levels (default: 5)

ScatterChart

Scatter (bubble) charts show relationships between two numeric dimensions. When colored or sized by additional fields, they become bubble charts.

{
  "type": "ScatterChart",
  "props": {
    "data": [
      [10, 20],
      [15, 35],
      { "value": [25, 45], "name": "Outlier", "color": "#ff0000" }
    ],
    "title": "Scatter Plot",
    "symbolSize": 12,
    "xAxisName": "X",
    "yAxisName": "Y"
  }
}

Key Props:

• data: [[x, y], ...] or [{ value: [x, y], name?, color? }, ...]
• symbolSize: Point size (number or [width, height])
• xAxisType / yAxisType: "value", "category", "time", or "log"
• xAxisMin / xAxisMax / yAxisMin / yAxisMax: Axis range

BoxplotChart

Boxplot charts (box-and-whisker) display statistical distributions through quartiles. Each box shows min, Q1, median, Q3, and max.

{
  "type": "BoxplotChart",
  "props": {
    "data": [
      [655, 850, 940, 980, 1175],
      [672, 800, 845, 885, 1012],
      [780, 840, 855, 880, 940]
    ],
    "xAxisData": ["Experiment 1", "Experiment 2", "Experiment 3"],
    "title": "Statistical Distribution"
  }
}

Key Props:

• data: [[min, Q1, median, Q3, max], ...] or [{ value: [...], name? }, ...]
• xAxisData: Category labels for each box
• boxStyle: Custom box appearance with color, borderColor, borderWidth

Common Props

All charts support these common properties:

Layout

| Prop | Type | Default | Description | |------|------|---------|-------------| | width | number \| string | "100%" | Chart width | | height | number \| string | 400 | Chart height |

Title

| Prop | Type | Description | |------|------|-------------| | title | string | Main title text | | titleSubtext | string | Subtitle text |

Legend

| Prop | Type | Default | Description | |------|------|---------|-------------| | showLegend | boolean | true (multi-series) | Show/hide legend | | legendPosition | "top" \| "bottom" \| "left" \| "right" | "top" | Legend position |

Tooltip

| Prop | Type | Default | Description | |------|------|---------|-------------| | showTooltip | boolean | true | Show/hide tooltip |

Axis (LineChart, BarChart)

| Prop | Type | Description | |------|------|-------------| | xAxisName | string | X-axis name | | yAxisName | string | Y-axis name | | showXAxis | boolean | Show X-axis | | showYAxis | boolean | Show Y-axis |

Animation

| Prop | Type | Default | Description | |------|------|---------|-------------| | animation | boolean | true | Enable animations | | animationDuration | number | 1000 | Duration in ms |

Events

All components support events:

{
  "type": "LineChart",
  "props": { "..." },
  "on": {
    "click": "handleChartClick",
    "legendselectchanged": "handleLegendChange"
  }
}

Available events:

• click: Triggered when clicking on data points (all charts)
• legendselectchanged: Triggered when toggling legend items (LineChart, PieChart, BarChart)

Exports

| Entry Point | Exports | |-------------|---------| | @json-render-plugins/echarts | echartsComponents | | @json-render-plugins/echarts/catalog | echartsComponentDefinitions, EChartsProps, ComponentDefinition, BindingsConfig, EmitFunction |

The /catalog entry point contains only Zod schemas (no React dependency), so it can be used in server-side code for prompt generation.

License

MIT