ChartBuddy Embed API (@chartbuddy.io/embed)

Create ChartBuddy Insights in any web page. Default is view-only (headless draw): hover the top-left ChartBuddy ball for Download (PNG), Export config (JSON), and Edit (full interactive editor). Pass editable: true to open the editor immediately. Spreadsheet is not included. No account or chart ID required: pass data via chartData.

Public API: Insight (via new Insight()), getInsights, snapshotInsights, version. Global registry: window.__CHARTBUDDY_INSIGHTS__.

Every JS entry (package root, .single.mjs, multi loader) opens with a comment header naming the exports and a minimal example. Agents: start at llms.txt, then fetch linked docs .md pages as needed. Also: https://unpkg.com/@chartbuddy.io/embed/llms.txt · https://chartbuddy.io/embed/docs/llms.txt. Package root on unpkg resolves to a readable stub that re-exports the single-file build.

Claude / strict CSP (recommended)

import { Insight } from 'https://unpkg.com/@chartbuddy.io/embed';
// equivalent:
// import { Insight } from 'https://unpkg.com/@chartbuddy.io/embed/chartbuddy-embed.single.mjs';

<div id="chart" style="width:960px;height:560px"></div>
<script type="module">
  import { Insight } from 'https://unpkg.com/@chartbuddy.io/embed';

  // Default: view-only + ChartBuddy hover ball
  new Insight('#chart', {
    instanceId: 'revenue', // stable id for multi-mount
    chartData: {
      chartType: 'clusteredBar',
      isDataTransposed: true,
      seriesData: [
        ['', 'Q1', 'Q2', 'Q3', 'Q4'],
        ['Revenue', 100, 112, 125, 140],
        ['Costs', 60, 66, 70, 78],
      ],
      title: { visible: true, text: 'Revenue vs Costs' },
      subtitle: { visible: false, text: '' },
    },
  });

  // Full editor: new Insight('#chart', { editable: true, chartData: … })
</script>

Do not pass assetBase on this path. Bundler: import { Insight } from '@chartbuddy.io/embed'.

Install / multi-file (normal websites)

npm install @chartbuddy.io/embed

Cache-friendly multi-file loader (siblings OK when CSP allows):

https://unpkg.com/@chartbuddy.io/embed/chartbuddy-embed.mjs

or import { Insight } from '@chartbuddy.io/embed/multi'.

With React

Use the bundled bindings — they handle StrictMode's double mount, patch the live chart on data changes instead of remounting, and destroy on unmount.

import { InsightChart } from '@chartbuddy.io/embed/react';

export function ChartEmbed({ chartData }) {
  return <InsightChart chartData={chartData} style={{ width: '100%', height: 560 }} />;
}

react is an optional peer dependency (React 18 or 19). For imperative access to the instance:

import { useInsight } from '@chartbuddy.io/embed/react';

const { ref, insight, ready, error } = useInsight({ chartData, editable: true });
// <div ref={ref} style={{ height: 400 }} />

chartData is compared by identity — memoize it if you build it inline.

Without a bundler, a plain HTML page needs an import map mapping both react and the subpath (which needs the explicit .mjs file):

<script type="importmap">{"imports":{
  "react": "https://esm.sh/react@19",
  "react-dom/client": "https://esm.sh/react-dom@19/client",
  "@chartbuddy.io/embed/react": "https://unpkg.com/@chartbuddy.io/embed/react.mjs"
}}</script>

Use React.createElement there — no build step means no JSX. For a standalone artifact, plain new Insight() or the custom element is simpler than either.

With Vue 3

<script setup>
import { InsightChart } from '@chartbuddy.io/embed/vue';
</script>

<template>
  <InsightChart :chart-data="chartData" style="height: 400px" @change="onChange" />
</template>

vue is an optional peer dependency. useInsight() is also exported for imperative access. Assign a new object to chartData to patch the chart — mutating in place is not detected.

With Angular (and Svelte / Solid / plain HTML)

Angular uses the <chartbuddy-insight> custom element rather than a compiled Angular library, so ChartBuddy upgrades are not tied to your Angular major. No peer dependency.

import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@chartbuddy.io/embed/element';

// template:
// <chartbuddy-insight [chartData]="cd" instance-id="revenue"
//                     style="display:block; height:400px"
//                     (change)="onChange($event)"></chartbuddy-insight>

chartData must be set as a property (it is an object). Events are CustomEvents — read event.detail. Full guide: https://chartbuddy.io/embed/docs/guides/angular

Usage (script tag / global)

<script src="https://unpkg.com/@chartbuddy.io/embed/chartbuddy-embed.global.js"></script>
<script>new ChartBuddyEmbed.Insight('#chart');</script>

Single-file IIFE: chartbuddy-embed.single.global.js.

API

new Insight(target: string | HTMLElement, options?: {
  chartData?: object;   // ChartBuddy chart-data (cd) — see below
  assetBase?: string;   // multi-file only; ignored by single-file
  editable?: boolean;   // default false → view mode; true → full editor
  allowEdit?: boolean;  // default true; false = Download/Drag only (no Edit)
  editSession?: 'toggle' | 'locked'; // locked = always edit, no mode chrome
  host?: {              // optional chrome hooks
    getToolbarPlacement?: () => object; // widget (default) | float | dock
    getToolbarContainer?: () => string | Element | null;
    positionToolbar?: (toolbar, target) => void; // float only
    getPopupContainer?: () => string | Element | null; // menus; default body
    startDragging?: (event) => void;
  };
  engineFlags?: {       // engine features still being built; all off by default
    arrowGeometry?: boolean; // arrows clear bars and total labels (see below)
  };
}): {
  container: HTMLElement;
  assetBase: string;
  instanceId: string;
  chartContainerId: string;
  mode: 'view' | 'edit';
  editSession: 'toggle' | 'locked';
  allowEdit: boolean;
  ready: Promise<void>;
  chart: any | null;
  focus(): void;
  setChartData(cd: object): void;   // partial OK — chartType optional
  setData(seriesData: any[][]): void;
  update(patch?: object): void;     // no arg = redraw only
  getChartData(): object | null;
  on(event: 'ready' | 'mode' | 'change', handler: Function): () => void;
  off(event: 'ready' | 'mode' | 'change', handler: Function): void;
  isDirty(): boolean;
  getRevision(): number;
  toPngBlob(options?: { scale?: number; background?: string | null }): Promise<Blob>;
  toPngBase64(options?: { scale?: number; background?: string | null }): Promise<string>;
  // PNG helpers default background to #ffffff; downloadPng defaults transparent
  downloadPng(options?: { scale?: number; background?: string | null }): Promise<void>;
  dragExport(): Promise<void>;
  exportConfig(): void;
  enterEditMode(): Promise<void>;  // view → edit (no-op if allowEdit: false)
  exitEditMode(): Promise<void>;   // edit → view (also ball → Done)
  destroy(): void;
};

getInsights(): Record<string, Insight>;
snapshotInsights(options?: {
  png?: boolean;
  scale?: number;
  background?: string | null;
}): Promise<{ schemaVersion: 1; version: string; charts: Record<string, any> }>;
version: string;

Engine flags (engineFlags)

Features of the chart engine that are still being built can be turned on per page before they are on for everyone. A flag applies to every chart on the page from its next draw, and goes away once the feature is on by default.

• arrowGeometry: difference arrows (and later CAGR and level arrows) are positioned by one shared calculation, so they clear the bars and total labels they span and the chart keeps room for them instead of clipping them. Arrows in existing charts may move when it is on.

new Insight('#chart', { chartData, engineFlags: { arrowGeometry: true } });

View mode (default)

• Headless chart draw (no formatting toolbar / selection chrome).
• On hover: ChartBuddy ball (top-left) → Download PNG, Drag to slide, Edit.
• enterEditMode() / ball Edit remounts the full editor with the current chartData.

Display-only (allowEdit: false)

• Same view ball and exports, but Edit is omitted.
• enterEditMode() is a no-op.

Edit mode (editable: true)

• Interactive ChartBuddy editor with formatting UI.
• Default toolbar placement is widget (modules in the morph rail). Override with host.getToolbarPlacement.
• Leave via ball Done or exitEditMode() (returns to view with current config).

Locked edit (editSession: 'locked')

• Always-on editor: no Done / morph.
• enterEditMode() / exitEditMode() are no-ops.
• Use when the host page owns surrounding chrome (demos, dialogs).

chartData (cd) schema

options.chartData is a ChartBuddy chart-data object. Partial objects are merged over defaults (nested title / subtitle / legend / axes / canvas / footnote are deep-merged).

Required

Recommended

Allowed chartType values

CHARTBUDDY:GENERATED-CHART-TYPES:BEGIN barMekko · clusteredBar · combo · line · mekko · pie · scatter stackedArea · stackedArea100 · stackedBar · stackedBar100 waterfall

Also accepted: bubble → scatter, donut → pie. CHARTBUDDY:GENERATED-CHART-TYPES:END

Aliases are shortcuts that seed defaults — they are not just renames:

For a donut, just pass chartType: 'donut' — setting innerRadiusRatio yourself is only needed to override the hole size. getChartData() returns pie with innerRadiusRatio: 0.5, which round-trips correctly.

Validation

Chart data is validated at the API boundary — both new Insight({ chartData }) and setChartData() / setData() / update(). Invalid input throws with the path of every problem, so you get one actionable error instead of a blank chart:

insight.setChartData({ chartType: 'pie', pie: { innerRadiusRatio: 5 } });
// Error: [chartbuddy/embed] setChartData: invalid chart data — 1 problem:
//   • pie.innerRadiusRatio: 5 is above the maximum of 1

What is checked: chartType (with a did-you-mean hint), field types, enums, numeric ranges, the seriesData grid (including the per-type row/column minimums listed above), and whether an option bag matches the chart type — bar options on a pie chart are rejected. Ragged seriesData (unequal row lengths) warns but does not throw. Duplicate instanceId values on the same page throw.

Unknown keys are never an error, so a config written for a newer version still loads. chart-schema.json is the machine-readable form of the same rules, usable for your own validation or to constrain generated or structured chartData.

Checking without mounting

The same checks are exported. validateChartData() never throws and reports everything it found, which is what you want when a model authored the config:

import { validateChartData } from '@chartbuddy.io/embed';

const { valid, errors, warnings } = validateChartData(candidate);
// errors[0] → {
//   path: 'chartType',
//   code: 'unknown-chart-type',
//   severity: 'error',
//   message: '"clusterdBar" is not a known chart type. Did you mean "clusteredBar"?',
//   expected: 'a ChartType or alias',
//   received: '"clusterdBar"',
//   allowed: ['barMekko', 'clusteredBar', 'stackedArea', …],
//   suggestion: 'clusteredBar',
// }

code and path are the stable contract — branch on code, repair the value at path, and never parse message. Codes: not-an-object, unknown-chart-type, empty-patch, wrong-type, out-of-range, not-in-enum, series-data-shape, ragged-series-data (warning), foreign-option-bag.

Throws carry the same objects:

import { ChartDataValidationError } from '@chartbuddy.io/embed';

try {
  insight.setChartData(candidate);
} catch (err) {
  if (err instanceof ChartDataValidationError) console.log(err.errors);
}

Partial updates

await insight.ready;
insight.setData([['', 'Q1'], ['Revenue', 120]]);  // data only
insight.update({ title: { text: 'FY26' } });       // any partial patch
insight.update();                                  // redraw only

setChartData also accepts partials — chartType is not required.

Events

insight.on('ready', () => { … });
insight.on('mode', (mode) => { … });          // 'view' | 'edit'
insight.on('change', (cd) => { … });          // after meaningful edits
insight.isDirty();                            // true since boot / last Done
insight.getRevision();                        // monotonic edit counter

seriesData layout (recommended)

With isDataTransposed: true, use chart-native rows-as-series:

[
  ['',        'Q1', 'Q2', 'Q3'],  // row 0: categories ( [0][0] usually "" )
  ['Revenue', 100,  112,  125],  // each later row = one series
  ['Costs',    60,   66,   70],
]

Pie (category / value pairs):

[
  ['Category', 'Value'],
  ['North', 45],
  ['South', 30],
  ['East', 25],
]

Scatter (transpose not supported):

[
  ['', 'Metric X', 'Metric Y', 'Size', 'Group'],
  ['Point 1', 10, 15, 8, 'A'],
  ['Point 2', 20, 12, 5, 'B'],
]

Minimal example

{
  chartType: 'clusteredBar',
  isDataTransposed: true,
  seriesData: [
    ['', 'Q1', 'Q2', 'Q3'],
    ['Revenue', 100, 112, 125],
  ],
  title: { visible: true, text: 'Revenue' },
  subtitle: { visible: false, text: '' },
}

Full config

The richest, safest cd is a snapshot from a live editor via insight.getChartData() (or insight.exportConfig()) after ready. Pass that JSON back as chartData.

Optional advanced fields (present on full exports): canvas, axes, chartPositionPercentages, annotations, multilines, type-specific blocks (bar, line, area, pie, waterfall, mekko, combo), seriesLabels.

How it works

Single-file: d3 + DOMPurify + engine + CSS in one module — use for Claude.

Multi-file: small loader pulls siblings (webapp-entry.js, vendors, CSS, worker). Use on sites you control.

Security: where chartData comes from

chartData is rendered as given. The engine treats it as a document you authored, not as untrusted input, so if the chart data on your page can be influenced by your own end users, treat it the way you would treat any user-supplied content.

The concrete case worth knowing about: font family names in chart data are used to request web fonts. ChartBuddy validates them and refuses names that could escape a stylesheet, but a Content-Security-Policy on your page is the control that does not depend on us getting that right. If you render chart data that users can influence, set at minimum:

style-src  'self' 'unsafe-inline' https://fonts.googleapis.com;
font-src   'self' data: https://fonts.gstatic.com;
object-src 'none';

style-src and font-src bound where a stylesheet or font may be fetched from, so a malicious font name cannot turn into a request to a host you did not choose. 'unsafe-inline' is required for style-src because the engine sets inline styles while rendering; it does not weaken the origin allowlist above.

If your page's chart data only ever comes from your own backend or from charts your own team authored, this is defence in depth rather than a requirement.

Notes

• Multi-mount supported. Construct new Insight() multiple times in one document.
• No spreadsheet in this package.
• Default view mode has no formatting toolbar; use Edit or editable: true.
• Single-file uses main-thread label placement (no worker/wasm fetch).
• Requires a browser (document).

License

Proprietary evaluation license — © ChartBuddy. See the bundled LICENSE file.