Output Formats
PNG, JPEG, SVG, WebP, and PDF — when to use each, file size tradeoffs, and compatibility notes.
Format comparison
| Format | Type | Plan | |
|---|---|---|---|
| png | Raster (lossless) | All clients ✓ | All |
| jpeg | Raster (lossy) | All clients ✓ | All |
| svg | Vector | Poor support ✗ | All |
| webp | Raster (lossless) | Partial ⚠ | All |
| Document | Not applicable | Pro, Agency |
Free includes PNG, JPEG, SVG, and WebP; PDF needs Pro or Agency. 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.
{
"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
Card compositions are encoded at 92% quality; plain charts use the canvas library's default 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.
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
Encoded losslessly, so the pixels match the PNG. 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 — Pro and Agency plans
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 Pro or Agency. Requesting it on Free returns a 403 with "plan_required" body and a message that names the plan you need.
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.