Generate Chart.JS charts as image and embed them everywhere in emails, pdf reports, chat bots...!

Getting started

1. Add Chart.js Image to your project

Requirements: Rust 1.65+

Add to your Cargo.toml:

[dependencies]
chartjs_image = "6"

Feature Flags

• async (default): Enables async methods (to_buffer(), to_file(), to_data_uri())
• blocking: Enables blocking/sync methods (to_buffer_blocking(), to_file_blocking(), to_data_uri_blocking())
• full: Enables both async and blocking

# Async only (default)
chartjs_image = "6"

# Blocking only
chartjs_image = { version = "6", default-features = false, features = ["blocking"] }

# Both async and blocking
chartjs_image = { version = "6", features = ["full"] }

2. Import ChartJSImage library

use chartjs_image::ChartJSImage;

3. Generate a chart image

use chartjs_image::ChartJSImage;

fn main() {
    let chart = ChartJSImage::new()
        .chart(r#"{
            "type": "pie",
            "data": {
                "labels": ["Red", "Blue", "Yellow"],
                "datasets": [{
                    "data": [300, 50, 100]
                }]
            }
        }"#)
        .width("600")
        .height("300");

    // Get URL (sync, no HTTP request)
    let url = chart.to_url();
    println!("{}", url);
}

// Async example
use chartjs_image::ChartJSImage;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let chart = ChartJSImage::new()
        .chart(r#"{"type":"pie","data":{"labels":["Red","Blue"],"datasets":[{"data":[60,40]}]}}"#)
        .width("600")
        .height("300");

    // Download as bytes
    let buffer = chart.to_buffer().await?;

    // Save to file
    chart.to_file("chart.png").await?;

    // Get as data URI
    let data_uri = chart.to_data_uri().await?;
    // data:image/png;base64,iVBORw0KGgo...

    Ok(())
}

---

Table of Contents

• Enterprise support
• On-Premise support
• Constructor
  • Options
• Methods
  • to_url()
  • to_buffer() / to_buffer_blocking()
  • to_file() / to_file_blocking()
  • to_data_uri() / to_data_uri_blocking()
    • c(value) - Javascript/JSON definition of the chart. Use a Chart.js configuration object.
    • chart(value) - Javascript/JSON definition of the chart. Use a Chart.js configuration object.
    • width(value) - Width of the chart
    • height(value) - Height of the chart
    • backgroundColor(value) - Background of the chart canvas. Accepts rgb (rgb(255,255,120)), colors (red), and url-encoded hex values (%23ff00ff). Abbreviated as "bkg"
    • bkg(value) - Background of the chart canvas. Accepts rgb (rgb(255,255,120)), colors (red), and url-encoded hex values (%23ff00ff). Abbreviated as "bkg"
    • encoding(value) - Encoding of your "chart" parameter. Accepted values are url and base64.
    • icac(value) - image-charts enterprise account_id
    • ichm(value) - HMAC-SHA256 signature required to activate paid features
    • icretina(value) - retina mode

---

Constructor

Create an instance with builder pattern. See usage

// Free usage - default configuration
let chart = ChartJSImage::new();

// Enterprise & Enterprise+ subscriptions
let chart = ChartJSImage::builder()
    .secret("SECRET_KEY")
    .build();

// With custom timeout
let chart = ChartJSImage::builder()
    .secret("SECRET_KEY")
    .timeout(std::time::Duration::from_secs(10))
    .build();

// On-premise subscriptions
let chart = ChartJSImage::builder()
    .protocol("https")
    .host("custom-domain.tld")
    .port(443)
    .pathname("/chart.js/2.8.0")
    .secret("SECRET_KEY")
    .build();

• Back to Getting started
• Back to ToC

---

Methods

---

to_url() -> String

Get the full Image-Charts API url (signed and encoded if necessary)

Usage

use chartjs_image::ChartJSImage;

fn main() {
    let url = ChartJSImage::new()
        .chart(r#"{"type":"pie","data":{"labels":["Hello","World"],"datasets":[{"data":[60,40]}]}}"#)
        .width("700")
        .height("300")
        .to_url();

    println!("{}", url);
}

• Back to Getting started
• Back to ToC

---

to_buffer() -> Result<Vec<u8>, ChartJSImageError> (async)

to_buffer_blocking() -> Result<Vec<u8>, ChartJSImageError> (blocking)

Do a request to Image-Charts API with current configuration and yield image bytes

Usage (async)

use chartjs_image::ChartJSImage;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let buffer = ChartJSImage::new()
        .chart(r#"{"type":"pie","data":{"labels":["Hello","World"],"datasets":[{"data":[60,40]}]}}"#)
        .width("700")
        .height("300")
        .to_buffer()
        .await?;

    println!("Downloaded {} bytes", buffer.len());
    Ok(())
}

Usage (blocking)

use chartjs_image::ChartJSImage;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let buffer = ChartJSImage::new()
        .chart(r#"{"type":"pie","data":{"labels":["Hello","World"],"datasets":[{"data":[60,40]}]}}"#)
        .width("700")
        .height("300")
        .to_buffer_blocking()?;

    println!("Downloaded {} bytes", buffer.len());
    Ok(())
}

• Back to Getting started
• Back to ToC

---

to_file(path) -> Result<(), ChartJSImageError> (async)

to_file_blocking(path) -> Result<(), ChartJSImageError> (blocking)

Download chart and save to file

Usage (async)

use chartjs_image::ChartJSImage;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ChartJSImage::new()
        .chart(r#"{"type":"pie","data":{"labels":["Hello","World"],"datasets":[{"data":[60,40]}]}}"#)
        .width("700")
        .height("300")
        .to_file("chart.png")
        .await?;

    println!("Chart saved!");
    Ok(())
}

• Back to Getting started
• Back to ToC

---

to_data_uri() -> Result<String, ChartJSImageError> (async)

to_data_uri_blocking() -> Result<String, ChartJSImageError> (blocking)

Do a request to Image-Charts API with current configuration and yield a base64 encoded data URI

Usage (async)

use chartjs_image::ChartJSImage;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let data_uri = ChartJSImage::new()
        .chart(r#"{"type":"pie","data":{"labels":["Hello","World"],"datasets":[{"data":[60,40]}]}}"#)
        .width("100")
        .height("100")
        .to_data_uri()
        .await?;

    // Use in HTML: <img src="{data_uri}" />
    println!("{}", &data_uri[..50]);
    Ok(())
}

• Back to Getting started
• Back to ToC

---

Enterprise Support

Image-Charts Enterprise and Enterprise+ subscriptions remove the watermark and enable advanced features like custom-domain, high-resolution charts, custom fonts, multiple axis and mixed charts.

• Pricing and plan comparison
• Enterprise documentation

Usage

Once subscribed to a plan you will receive an ACCOUNT_ID and a SECRET_KEY. These two parameters are mandatory to sign your request and remove the watermark. Replace both values in the code example below:

use chartjs_image::ChartJSImage;

fn main() {
    let url = ChartJSImage::builder()
        .secret("SECRET_KEY")
        .build()
        .chart(r#"{"type":"pie","data":{"labels":["Hello","World"],"datasets":[{"data":[60,40]}]}}"#)
        .width("700")
        .height("190")
        .icretina("1")
        .icac("ACCOUNT_ID")
        .to_url();

    println!("{}", url);
}

• Back to Getting started
• Back to ToC

---

On-Premise Support

Image-Charts virtual appliance can be deployed anywhere inside a customer network.

use chartjs_image::ChartJSImage;

fn main() {
    let url = ChartJSImage::builder()
        .host("custom-domain.tld")
        .secret("SECRET_KEY")
        .build()
        .chart(r#"{"type":"pie","data":{"labels":["Hello","World"],"datasets":[{"data":[60,40]}]}}"#)
        .width("700")
        .height("190")
        .icretina("1")
        .icac("ACCOUNT_ID")
        .to_url();

    println!("{}", url);
    // https://custom-domain.tld/chart.js/2.8.0?c=...&ichm=...
}

• Back to Getting started
• Back to ToC

---

c( value ) -> ChartJSImage

Javascript/JSON definition of the chart. Use a Chart.js configuration object.

Usage

.c("{type:'bar',data:{labels:['Q1','Q2','Q3','Q4'],datasets:[{label:'Users',data:[50,60,70,180]},{label:'Revenue',data:[100,200,300,400]}]}}")

• Back to Getting started
• Back to ToC

---

chart( value ) -> ChartJSImage

Javascript/JSON definition of the chart. Use a Chart.js configuration object.

Usage

.chart("{type:'bar',data:{labels:['Q1','Q2','Q3','Q4'],datasets:[{label:'Users',data:[50,60,70,180]},{label:'Revenue',data:[100,200,300,400]}]}}")

• Back to Getting started
• Back to ToC

---

width( value ) -> ChartJSImage

Width of the chart

Usage

.width("400")

• Back to Getting started
• Back to ToC

---

height( value ) -> ChartJSImage

Height of the chart

Usage

.height("300")

• Back to Getting started
• Back to ToC

---

backgroundColor( value ) -> ChartJSImage

Background of the chart canvas. Accepts rgb (rgb(255,255,120)), colors (red), and url-encoded hex values (%23ff00ff). Abbreviated as "bkg"

Usage

.backgroundColor("black")

.backgroundColor("rgb(255,255,120)")

.backgroundColor("%23ff00ff")

• Back to Getting started
• Back to ToC

---

bkg( value ) -> ChartJSImage

Background of the chart canvas. Accepts rgb (rgb(255,255,120)), colors (red), and url-encoded hex values (%23ff00ff). Abbreviated as "bkg"

Usage

.bkg("black")

.bkg("rgb(255,255,120)")

.bkg("%23ff00ff")

• Back to Getting started
• Back to ToC

---

encoding( value ) -> ChartJSImage

Encoding of your "chart" parameter. Accepted values are url and base64.

Allowed values:

.encoding("url")

.encoding("base64")

• Back to Getting started
• Back to ToC

---

icac( value ) -> ChartJSImage

image-charts enterprise account_id

Reference

Usage

.icac("accountId")

• Back to Getting started
• Back to ToC

---

ichm( value ) -> ChartJSImage

HMAC-SHA256 signature required to activate paid features

Reference

Usage

.ichm("0785cf22a0381c2e0239e27c126de4181f501d117c2c81745611e9db928b0376")

• Back to Getting started
• Back to ToC

---

icretina( value ) -> ChartJSImage

retina mode

Reference

Allowed values:

.icretina("0")

.icretina("1")

• Back to Getting started
• Back to ToC