Chartlets

Line charts

Bar charts

Pie charts

Custom charts

What are Chartlets?

Chartlets are tiny charts without grids or legends, like Sparklines. They're perfect for conveying simple relationships or trends, especially when space is scarce.

Chartlets uses the HTML5 <canvas> element for fast performance and is only 2.8k when minified and gzipped. It has no dependencies.

Usage

1. Download and include <script src="chartlets.min.js"></script>.

2. Create a <canvas> element with a width, height, and the class name "chartlet." Then add HTML5 data attributes as described below.

3. Call Chartlets.render().

Examples

Chart Types

Chartlets includes three basic chart types:

<canvas class="chartlet" data-type="line" ...></canvas>

<canvas class="chartlet" data-type="bar" ...></canvas>

<canvas class="chartlet" data-type="pie" ...></canvas>

Chart Data

Data is expressed as one or more sets of y-values, depending on the chart type. Sets must be of equal length; x-scales are assumed to have even increments.

<canvas class="chartlet" data-type="line" ... data-sets="[1 2 3 4 5] [5 4 3 2 1]"></canvas>

<canvas class="chartlet" data-type="bar" ... data-sets="[1.5 2.5 3.5] [4.5 5.5 6.5]"></canvas>

<canvas class="chartlet" data-type="pie" ... data-sets="[10 20 30]"></canvas>

Scales are derived from the minimum and maximum data points unless explicited stated:

<canvas class="chartlet" ... data-range="0 10" data-sets="[1 3 5] [2 4 6]"></canvas>

Pro tip: Data can be expressed in shorthand notation (e.g. "[1 2] [3 4]") or JSON (e.g. "[[1, 2], [3, 4]]").

Chart Colors

Colors are expressed in hexadecimal, RGB(A) or HSL(A) notation, one color for each data set.

<canvas class="chartlet" ... data-colors="#f00 #bada55"></canvas>

<canvas class="chartlet" ... data-colors="rgb(255,0,0) rgba(10,20,30,0.5)"></canvas>

<canvas class="chartlet" ... data-colors="hsl(200, 83%, 50%) hsla(319, 83%, 50%, 0.5)"></canvas>

Themes

Instead of specifying an array of colors, you can apply a color theme:

<canvas class="chartlet" ... data-opts="theme:money"></canvas>

Pick from one of ten built-in themes, each with five colors:

Or create a custom theme using any number and combination of hex, RGB(A) or HSL(A) strings:

To load the current color set:

Or to load colors for a particular theme:

Chart Options

Chartlets can be customized via the data-opts attribute:

<canvas class="chartlet" data-type="line" ... data-opts="stroke:2 shape:smooth cap:circle"></canvas>

Global options

• bgcolor sets the background color of the entire chart. It can be in hex, RGB(A) or HSL(A) notation. The background is transparent by default.

• theme sets the color theme for the chart data, overriding any colors specified in data-colors. If no theme is specified and data-colors is empty, the "blues" theme is applied.

Line options

• stroke sets the line width, a value between 1 and 3, inclusive. The default value is 1.

• shape sets the line contour. Acceptable values are straight, smooth and step. The default value is straight.

• cap renders an icon at each data point. Acceptable values are none, circle and square. The default value is none.

• fill sets the fill style, either none or solid. The default value is none.

• alpha sets the opacity of the fill, a number between 0 and 1.0, inclusive. The default value is 0.5 (or 1.0 if transform is set to stack).

• transform specifies how to structure the data sets. Acceptable values are none and stack. If stack, data sets are "stacked" bottom to top. The default value is none.

• axis renders a dashed line at the given y-value.

Bar options

• orient sets the orientation of the chart, either horiz or vert. The default value is vert.

• transform specifies how to structure the data sets. Acceptable values are none and stack. If stack, data sets are "stacked" bottom to top. The default value is none.

• axis renders an axis line at the given y-value.

Updating Data

The update method helps you re-render charts with new data (or populate charts with data from an AJAX request). It accepts an element (or element ID) and an array of data sets. Below, the <canvas> element with ID "demo1" is updated with new values every 500ms.

var a = [2, 3, 5, 3, 6, 3, 7, 8, 4, 2];
var b = [8, 3, 4, 7, 2, 7, 2, 4, 6, 1];

setInterval(function() {
  a.push(Math.ceil(Math.random() * 9));
  b.push(Math.ceil(Math.random() * 9));
  a.shift();
  b.shift();

  Chartlets.update("demo1", [a, b]);
}, 500);

Here, a pie chart acts as a progress meter:

var a = 0;

setInterval(function() {
  if (++a > 100) {
    a = 0;
  }

  Chartlets.update("demo2", [[a, 100 - a]]);
}, 50);

Transitions

You can apply a transition effect during an update if the old and new data structures are identical. For example:

The only transition type is "linear." Try it out below:

Custom Chart Types

You can create your own chart type by writing a custom renderer. For example, say you want to draw a smiley face with a configurable smile:

The setRenderer method accepts a chart type and rendering function, which gives you direct access to the canvas context, chart data and other properties:

Chartlets.setRenderer("smiley", function (ctx, width, height, sets, opts) {
  // width = 75
  // height = 75
  // sets = [[1,2], [3,4]]
  // opts = { gender: "male", hair: "yes" }
  // colors = Chartlets.getTheme()

  // now draw into ctx
});

Transitions should work without any additional logic. Following on the above example, a smiley face might transition from a smile to a frown when the chart is updated:

Advanced Usages

• Bar Chart with Comingled Positive and Negative Values
• BarLine Chart
• Scatter Chart
• Bubble Chart
• Guage Chart
• Plotting Null Values
• Axis Calibration

Notes

• You can apply additional styles to the <canvas> element with CSS. For example: .chartlet { border: 1px solid #ddd; }

• Fixed: At this time, positive and negative values cannot be comingled in a stacked bar chart or stacked line chart.

• For older browsers that don't support the <canvas> element, consider a polyfill.

• For larger, canvas-based charts, consider Chart.js. For interactive, SVG-based charts, consider D3.js.

• Bugs or requests? Please submit an issue.