mjml-chartjs

An MJML component for embedding Chart.js charts in email using the open-source QuickChart renderer.

Usage

This mjml...

<mjml>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-chartjs chart="{
          type: 'bar',
          data: {
            labels: ['Q1', 'Q2', 'Q3', 'Q4'],
            datasets: [{
              label: 'Users',
              data: [50, 60, 70, 180],
              backgroundColor: 'rgb(75, 192, 192)',
            }]
          }
        }
        " />
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

Will show this chart:

Set the image's background color, width, height, and more using the attributes below.

To learn more about building and customizing charts with Chart.js, refer to the Chart.js documentation.

Setup

Install via npm:

npm install mjml-chartjs --save

Then add the package to your .mjmlconfig:

{
  "packages": [
    "mjml-chartjs/lib/MjChartjs.js"
  ]
}

Attributes

The <mj-chartjs> tag supports all the attributes of the <mj-image> tag. View those attributes here.

In addition to regular image attributes which you can using for sizing and positioning, the component supports the following chart-specific attributes:

Name	Description	Required?	Default
chart	The Chart.js configuration to be rendered	Yes
width	The pixel width of the generated chart image		500px
height	The pixel height of the generated chart image		300px
background-color	The background color of the generated chart image		#fff
chartjs-version	The version of Chart.js renderer to use		3
host	The host of the chart rendering server		quickchart.io
scheme	The scheme of the chart rendering server		https
ignore-url-limit	If set, ignore the 16kb URL length guideline		false
api-key	QuickChart.io API key (optional, for signing requests)
api-account	QuickChart.io account ID (optional, for signing requests)

Limitations

Large charts

If you have a very large chart config, it may not fit into an image tag! Browsers and web servers limit the max length of URLs. This plugin works by fully encoding the chart image into the image URL.

This plugin will throw an error if your URL length exceeds 16kb. You can override this behavior by setting the ignore-url-limit attribute on your mj-chartjs tag.

The good news is that you should almost never need to send a URL that long. If the chart URL is too long, consider the following:

• Is it possible to remove datapoints from the chart? You probably don't need to show that level of detail.
• Can you reduce the precision of your chart values? The user probably won't be able to see the difference between 1.0 and 1.000000025

If you decide that you want to send a large data payload anyways, consider pre-registering the charts as short URLs and then sending the shortened URLs in a regular mj-image tag.

No interactivity (animations or tooltips)

This package works by rendering your Chart.js chart as an image. This means it is not psosible to retain interactive chart features such as animations or tooltips.

Hosting

By default, this component uses the public QuickChart web service to render charts, but you can use the host attribute to point to your own chart renderer.