Output Formats

PNG, JPEG, SVG, WebP, and PDF — when to use each, file size tradeoffs, and compatibility notes.

Format comparison

Format	Type	Typical size	Email	Plan
png	Raster (lossless)	30–200 KB	All clients ✓	All
jpeg	Raster (lossy)	15–80 KB	All clients ✓	Starter+
svg	Vector	10–60 KB	Poor support ✗	Starter+
webp	Raster (lossy)	10–60 KB	Partial ⚠	Starter+
pdf	Document	50–300 KB	Not applicable	Business

Trial accounts are restricted to PNG. Set format in the request body or ?format= in the query string.

PNG — the default

Lossless raster format. Every email client supports it. PNG is the right choice unless you have a specific reason to use something else.

For retina displays, set scale: 2 to render at 2× resolution, then constrain the image with HTML width/height attributes set to the logical size.

json

{
  "type": "bar",
  "width": 800,
  "height": 400,
  "format": "png",
  "scale": 2
}

Produces a 1600×800 bitmap rendered at 2× density. In HTML: <img width="800" height="400" />.

JPEG — smaller file, lossy

Rendered at 92% quality. Useful when file size matters (newsletters with many images) and the chart doesn't have sharp edges or text — JPEG compression artifacts are more visible at those boundaries.

All major email clients support JPEG. Not supported on Trial plan.

SVG — scalable vector

Resolution-independent. Perfect for web pages, dashboards, and anywhere you need to zoom or embed in PDFs via other tools (e.g. pdfkit, Puppeteer). File sizes are small because they contain coordinates, not pixels.

Do not use SVG in email. Gmail, Outlook, and most mobile clients strip or block SVG.

Card compositions (header, kpiStrip, footer) always render as PNG even when format: "svg" is specified — the card shell is drawn on a canvas.

How SVG is rendered

SVG output uses Chart.js's vector backend when available. If the SVG canvas backend is unavailable in your deployment environment, Chart-Output falls back to a lossless PNG embedded within an SVG wrapper. The HTTP response is always image/svg+xml; the internal representation may vary.

Each SVG response carries the X-Svg-Backend header, set to either native (true vector output) or fallback (PNG-in-SVG). Use this if you need to detect vector fidelity programmatically.

WebP — modern raster

Typically 25–35% smaller than PNG at similar quality. Best for web pages where you control the browser environment. Outlook desktop and older clients do not support WebP, so avoid it in email.

PDF — Business plan

Chart-Output renders the chart as PNG and wraps it in a single-page PDF sized to the chart dimensions. The result is a print-ready document.

PDF output requires the Business plan. Requesting it on a lower plan returns a 403 with "PDF output requires the Business plan".

If you need to embed charts in a larger PDF document (multi-page reports), use PNG or JPEG and embed with a PDF library like pdfkit (Node.js) or ReportLab (Python). See the Charts in PDFs guide.

Email client compatibility

Client	PNG	JPEG	WebP	SVG
Gmail (web)	✓	✓	✓	✗
Gmail (mobile)	✓	✓	✓	✗
Outlook (web)	✓	✓	✓	✗
Outlook (desktop)	✓	✓	✗	✗
Apple Mail	✓	✓	✓	partial
Yahoo Mail	✓	✓	✗	✗
Samsung Mail	✓	✓	✓	✗

Use PNG for broadest compatibility. If Outlook desktop is in your audience (common in enterprise), avoid WebP. See the Charts in Email guide for complete embedding patterns.