Docs menu
Charts in email
Size, format and markup for charts in report emails.
Email can't run JavaScript, so a chart in an email has to be an image. A Chartshot URL in an <img> is that image, and nothing has to be uploaded or hosted.
Use the email preset
"preset": "email" draws the chart at 600 × 300, the width of most email templates' content column. At the default scale of 2 the PNG is 1200 × 600, so it stays sharp on high-density screens.
{
"type": "bar",
"theme": "midnight",
"data": {
"labels": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
"series": [
{
"name": "Signups",
"values": [142, 168, 155, 189, 204, 96, 88]
}
]
},
"options": {
"title": "Signups this week",
"valueLabels": true,
"grid": false,
"yAxis": {
"hidden": true
}
},
"preset": "email"
}Write the img tag
Set width and height to the chart's size, so the layout doesn't jump while the image loads. The style lets it shrink to fit a phone's screen:
<img src="https://api.chartshot.dev/v1/chart?c=eyJ0eXBlIjoiYmFyIiwidGhlbWUiOiJtaWRuaWdodCIsImRhdGEiOnsibGFiZWxzIjpbIk1vbiIsIlR1ZSIsIldlZCIsIlRodSIsIkZyaSIsIlNhdCIsIlN1biJdLCJzZXJpZXMiOlt7Im5hbWUiOiJTaWdudXBzIiwidmFsdWVzIjpbMTQyLDE2OCwxNTUsMTg5LDIwNCw5Niw4OF19XX0sIm9wdGlvbnMiOnsidGl0bGUiOiJTaWdudXBzIHRoaXMgd2VlayIsInZhbHVlTGFiZWxzIjp0cnVlLCJncmlkIjpmYWxzZSwieUF4aXMiOnsiaGlkZGVuIjp0cnVlfX0sInByZXNldCI6ImVtYWlsIn0" width="600" height="300" alt="Signups this week" style="display: block; max-width: 100%; height: auto;">Write alt text that says what the chart shows. Many email clients hold images back until the reader allows them, and show the alt text in their place. The API's own description of the chart comes back in the X-Chart-Alt header if you want to use it.
Keep it PNG
PNG is the default format, and every email client shows it. Support for SVG and WebP varies from client to client (Can I email), and Gmail, for one, converts them to PNG and JPEG.
Keep the theme's background
Leave background at its default, the theme's own colour. Some email clients darken the message in dark mode, and a chart with a transparent background then puts dark text on a dark page. A chart on its own background reads the same in both.
The chart is fixed when you send it
The data is in the URL, so the email shows the numbers it was sent with, however late it's opened. To show this week's numbers, send a new URL in this week's email.
react-email
With react-email, pass the URL to Img with the same size and alt text:
import { Img } from "@react-email/components";
const spec = {
"type": "bar",
"theme": "midnight",
"data": {
"labels": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
"series": [
{
"name": "Signups",
"values": [142, 168, 155, 189, 204, 96, 88]
}
]
},
"options": {
"title": "Signups this week",
"valueLabels": true,
"grid": false,
"yAxis": {
"hidden": true
}
},
"preset": "email"
};
const c = Buffer.from(JSON.stringify(spec)).toString("base64url");
const url = `https://api.chartshot.dev/v1/chart?c=${c}`;
export function SignupsChart() {
return <Img src={url} width="600" height="300" alt="Signups this week" />;
}Preview it
The playground has an email preview that shows the chart inside a Gmail or Outlook message at its real size.