The JSON spec

A spec is an object with a type, which is a component's kebab-case name, plus that component's props.

{ "type": "bar-chart", "data": [{ "month": "May", "tickets": 51 }], "x": "month", "y": "tickets" }

Insight renders it. Edit the JSON on the left. The figure on the right redraws each time the JSON is valid.

import { useState } from "react";
import { Insight, type InsightSpec } from "insightcharts";

const initial = `{
  "type": "bar-chart",
  "title": "Support tickets fell from 84 in March to 43 in June",
  "subtitle": "Tickets per 1,000 accounts",
  "data": [
    { "month": "Mar", "tickets": 84 },
    { "month": "Apr", "tickets": 79 },
    { "month": "May", "tickets": 51 },
    { "month": "Jun", "tickets": 43 }
  ],
  "x": "month",
  "y": "tickets",
  "highlight": "Jun",
  "annotations": [{ "type": "line", "axis": "y", "value": 60, "label": "Target: 60" }],
  "height": 260
}`;

export default function JsonLive() {
  const [text, setText] = useState(initial);
  const [spec, setSpec] = useState<InsightSpec>(() => JSON.parse(initial));
  const [error, setError] = useState("");

  function edit(next: string) {
    setText(next);
    try {
      const parsed = JSON.parse(next);
      // Keep the last valid spec on screen while the JSON is mid-edit.
      if (parsed && typeof parsed.type === "string") setSpec(parsed);
      setError(typeof parsed?.type === "string" ? "" : 'A spec needs a "type".');
    } catch (e) {
      setError((e as Error).message);
    }
  }

  return (
    <div style={{ display: "grid", gridTemplateColumns: "repeat(auto-fit, minmax(280px, 1fr))", gap: 24, alignItems: "start" }}>
      <div style={{ display: "grid", gap: 6, minWidth: 0 }}>
        <textarea
          value={text}
          onChange={(e) => edit(e.target.value)}
          spellCheck={false}
          aria-label="JSON spec"
          rows={19}
          style={{ width: "100%", resize: "vertical", fontFamily: "var(--font-mono)", fontSize: 12.5, lineHeight: 1.6, padding: 12, borderRadius: 8, border: "1px solid var(--border)", background: "transparent" }}
        />
        <p role="status" style={{ fontSize: 12, minHeight: 18, margin: 0, opacity: 0.7 }}>
          {error || "Valid spec. Try changing the type to line-chart or the highlight to Mar."}
        </p>
      </div>
      <div style={{ minWidth: 0 }}>
        <Insight spec={spec} />
      </div>
    </div>
  );
}

What a spec can contain#

Almost every prop is JSON-serialisable:

• Fields are names, not accessor functions: x: "month".
• Data reshaping is a list of transform objects, not code.
• Number formats are strings: "compact", "percent", "{value} kg".
• Annotations are objects in data coordinates.
• Remote data is a URL or { url, path }.

Only callbacks (onSelect, onEvents, onReady) and the function forms of option, format, transform and data cannot be expressed. A spec that needs none of them can be stored in a database, returned by an API or produced by a model.

Rendering specs#

import { Insight } from "insightcharts";

export function Answer({ spec }) {
  return <Insight spec={spec} />;
}

Insight can render any atom, molecule or template, so it pulls all of them into the bundle. Prefer named imports (BarChart) when you know the chart at build time and bundle size matters, and Insight when the chart is chosen at runtime. The components are registered the first time an Insight renders, not when the module is imported.

If type is not a known component, Insight renders an inline alert that lists the available names rather than throwing. You can send that message back to a model so it can correct the spec.

Nested specs#

Molecules and templates take content through slot props. A slot accepts either rendered React content or another spec, so a whole page can be written as one JSON document.

import { ChartCallout, registerAll } from "insightcharts";

// The slot props below are JSON specs. This makes their `type` names resolvable.
registerAll();

export function Example() {
  return (
    <ChartCallout
      chart={{
        type: "line-chart",
        data: [
          { month: "Jan", churn: 4.2 },
          { month: "Mar", churn: 4.1 },
          { month: "May", churn: 3.1 },
          { month: "Jul", churn: 2.6 },
          { month: "Sep", churn: 2.3 },
          { month: "Nov", churn: 2.1 },
        ],
        x: "month",
        y: "churn",
        format: "{value}%",
        zero: true,
        height: 240,
        title: "Monthly churn fell from 4.2% in January to 2.1% in November 2024",
        subtitle: "Monthly customer churn, 2024",
        note: "Illustrative data",
      }}
      lead="Churn was 2.1% in November"
      body="The largest fall between two readings was from 4.1% in March to 3.1% in May."
    />
  );
}

{
  "type": "chart-callout",
  "chart": {
    "type": "line-chart",
    "data": [
      { "month": "Jan", "churn": 4.2 },
      { "month": "Mar", "churn": 4.1 },
      { "month": "May", "churn": 3.1 },
      { "month": "Jul", "churn": 2.6 },
      { "month": "Sep", "churn": 2.3 },
      { "month": "Nov", "churn": 2.1 }
    ],
    "x": "month",
    "y": "churn",
    "format": "{value}%",
    "zero": true,
    "height": 240,
    "title": "Monthly churn fell from 4.2% in January to 2.1% in November 2024",
    "subtitle": "Monthly customer churn, 2024",
    "note": "Illustrative data"
  },
  "lead": "Churn was 2.1% in November",
  "body": "The largest fall between two readings was from 4.1% in March to 3.1% in May."
}

Here chart is a slot of chart with callout, and its value is a line chart spec. Each molecule and template page lists its slot props and shows a complete example under the JSON tab; templates walks through a whole page built this way.

Nested specs are looked up by name. Insight does this for you. When you render the outer component yourself with a named import and pass specs into its slots, as the Code tab above does, fill the registry first. registerAll() registers everything; registerComponents registers only what you name, which keeps the rest out of the bundle.

import { ChartCallout, LineChart, registerAll, registerComponents } from "insightcharts";

registerAll();
// or, to keep the bundle small:
registerComponents({ LineChart });

<ChartCallout chart={{ type: "line-chart", data, x: "month", y: "churn" }} lead="Churn was 2.1% in November" />

A slot spec that names an unregistered component renders an inline alert saying so, in place of the chart.

Validating a spec#

The component catalogue is published as JSON Schema, generated from the same metadata as this site:

• /schema/insight-spec.json: the schema for a spec.
• /schema/manifest.json: every component's name, level, props, example and what it composes.

Pass the schema to a model as a structured-output or tool schema and its answers are constrained to components and props that exist.

Helpers#