Chart-OutputChart-OutputDashboard

Chart Specifications

Chart-Output uses a JSON specification compatible with Chart.js. All charts are rendered server-side via POST /api/v1/render.

Chart Types

  • line – Line chart
  • bar – Bar chart
  • pie – Pie chart
  • doughnut – Doughnut chart
  • radar – Radar chart
  • polarArea – Polar area chart

Output Formats

  • png – PNG image (default). Best for email embeds.
  • jpeg – JPEG image
  • svg – Scalable vector graphic (note: card composition renders as PNG even when svg is specified)
  • webp – WebP image (smaller file size)
  • pdf – PDF document (Pro plan required)

Dimensions & Limits

  • Width/height: 100–4000 px (default 800×400)
  • Max labels: 1000
  • Max data points per dataset: 1000
  • Max datasets: 20

Resolution & retina (scale / devicePixelRatio)

On POST /api/v1/render, the default is 1×: bitmap dimensions match width and height.

GET /api/v1/templates/{id}/render defaults to 2× when scale is omitted. Pass scale=1 for 1× output.

For high-DPI output (e.g. 800×400 logical → 1600×800 bitmap), set devicePixelRatio: 2 or the alias scale: 2. Allowed range is 1–4. In HTML email, use a 2× image with width/height set to the logical size.

Dataset Options

Each dataset can include:

json
{ "label": "Revenue", "data": [12000, 15000, null, 18000], "backgroundColor": "#3b82f6", "borderColor": "#1d4ed8", "borderWidth": 2, "fill": true, // Line / radar only "tension": 0.4, "borderDash": [6, 3], "pointRadius": 4, // Bar only "barPercentage": 0.8, "borderRadius": 4, "stack": "group1" }

null values create gaps in line and radar charts (Chart.js sparse data). Other chart types should use numeric values only.

Theme

The optional theme object provides per-request color and font overrides. It takes highest priority in the merge chain (above brand kit and template defaults):

json
{ "type": "bar", "data": { ... }, "theme": { "palette": ["#e85729", "#3a6cf5", "#0f9d72"], "backgroundColor": "#0f172a", "fontFamily": "Inter", "fontSize": 13, "gridColor": "rgba(148,163,184,0.18)", "mode": "dark", "textPrimary": "#f0f6fc", "textSecondary": "#6e7681" } }

The schema uses .passthrough() on theme, so additional keys may be merged by the theme pipeline when supported.

Padding Presets

The root padding field accepts one of "email", "slack", or "pdf" — each maps to fixed layout padding merged into options.layout.padding. For arbitrary padding, set options.layout.padding directly in Chart.js style.

  • email – 24px top/right, 16px bottom/left
  • slack – 12px top/right, 8px bottom/left (compact)
  • pdf – 32px top/right, 24px bottom/left
json
{ "type": "bar", "padding": "email", "data": { ... } }

Data Labels

Set dataLabels: true to enable on-chart value labels via chartjs-plugin-datalabels. This is a shorthand for the full plugin config under options.plugins.datalabels:

json
{ "type": "bar", "dataLabels": true, "data": { "labels": ["Q1", "Q2", "Q3"], "datasets": [{ "data": [100, 150, 120] }] } }

Annotations

The annotations array adds reference lines or shaded boxes via chartjs-plugin-annotation:

json
{ "type": "line", "annotations": [ { "type": "line", "axis": "y", "value": 20000, "label": "Target", "color": "#e85729" }, { "type": "box", "xMin": "Feb", "xMax": "Mar", "label": "Launch window", "color": "rgba(59,130,246,0.14)" } ], "data": { ... } }

Brand Kits

Pass brandKitId (UUID or preset name) to apply custom colors, fonts, grid style, and corner rounding. Named presets: obsidian, linen, polar, studio, ember, harbor.

Advanced Options

The options object is passed directly to Chart.js. Use it for custom scales, plugins, and styling. Animations are disabled for server-side rendering. The server registers chartjs-plugin-datalabels and chartjs-plugin-annotation.

Root-level shorthands (dataLabels, annotations) are normalized into options.plugins server-side. Full options.plugins.datalabels / options.plugins.annotation objects still work and take precedence where specified.

Card Composition

Chart-Output can render a full designed card — not only the chart. Optional root-level fields add a header row, canvas legend, KPI strip, footer, outer border, and themed shell around the Chart.js plot. Card fields sit alongside type, data, and options; they are validated in lib/validation/chart-spec.ts.

Card-level and card-adjacent fields (one line each):

  • backgroundColor – Outer card fill when card composition is active
  • borderRadius – Outer corner radius (0–64 px)
  • border – { color, width } for the card outline
  • padding – Named preset: email, slack, or pdf
  • scale / devicePixelRatio – Retina multiplier (1–4), alias pair
  • theme – Token overrides (palette, fonts, grid, textPrimary / textSecondary, etc.)
  • header – Eyebrow, title, subtitle, badge, alignment
  • legend – Canvas legend row (display, position, style, fontSize, gap)
  • kpiStrip – Up to 12 KPI items (label, value, color)
  • footer – Left/right text and optional top border
  • dataLabels – Boolean shorthand for datalabels plugin
  • annotations – Showcase line/box annotations (mapped to plugin)
  • brandKitId – Preset name or saved kit UUID
  • returnUrl – Return JSON with CDN URL instead of raw image

Full examples, anatomy, and per-field types: Card Composition.