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:

Customize the background color, width, height, and other parameters using the attributes below.

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 QR-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) | | |

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.

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.