Novice, Practiced, Mastered

    mjml-chartjs

    1.0.0 • Public • Published

    mjml-chartjs

    Build Status

    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:

    MJML rendered 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.

    Keywords

    none

    Install

    npm i mjml-chartjs

    DownloadsWeekly Downloads

    16

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    26.9 kB

    Total Files

    15

    Last publish

    Collaborators

    • ianw