In this section you'll go through a simple example of how to use Chartist.js in your project. You'll learn the default stages you go through when creating and customizing a basic line chart. If you'd like to see more in depth and advanced examples you should check out the advanced section or the examples page.
As simple as it can get
Chartist provides you a very simple API to get started, however, while trying to follow the best practice of relying on standards and clear separation of concerns it sometimes needs a small mind shift in order to understand how things are meant to work within Chartist. Instead of specifying your colors, line width and other style related things in the JavaScript API, you'll need to use CSS in order to control your appearance.
Creating a chart using aspect ratios
Because of the nature of responsive design it's important to understand that blocks in design like images, videos and similar content need to be able to scale and adapt to the media. In order for an element to scale, you need to rely on a certain aspect ratios (like 4:3, 3:2, 16:9 etc.) rather than specifying a fixed width and height.
To designers this Idea is absolutely not new, but to developers this might be at first. However, when a designer talks to a developer about the images being 320x240 on this page and 300x200 on that element, he actually just translated his idea of using 4:3 and 3:2 images into pixels.
With Chartist you can specify those ratios directly on containers without the need to calculate any fixed dimensions. In order to create a chart that is using the aspect ratio of a golden section you can just add the class .ct-golden-section to your container where you initialize Chartist.
Here is a list of all available container ratios (If using the Sass version of Chartist you can also easily add others):
Show available aspect ratios| Container class | Ratio |
|---|
| .ct-square | 1 |
| .ct-minor-second | 15:16 |
| .ct-major-second | 8:9 |
| .ct-minor-third | 5:6 |
| .ct-major-third | 4:5 |
| .ct-perfect-fourth | 3:4 |
| .ct-perfect-fifth | 2:3 |
| .ct-minor-sixth | 5:8 |
| .ct-golden-section | 1:1.618 |
| .ct-major-sixth | 3:5 |
| .ct-minor-seventh | 9:16 |
| .ct-major-seventh | 8:15 |
| .ct-octave | 1:2 |
| .ct-major-tenth | 2:5 |
| .ct-major-eleventh | 3:8 |
| .ct-major-twelfth | 1:3 |
| .ct-double-octave | 1:4 |
Use the following HTML code to specify a container with one of the above aspect ratio classes.
<div class="ct-chart ct-perfect-fourth"></div>
When using a fixed aspect ratio container you can then simply initialize your chart without specifying any width or height in the options.
var data = {
// A labels array that can contain any sort of values
labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
// Our series array that contains series objects or in this case series data arrays
series: [
[5, 2, 4, 2, 0]
]
};
// Create a new line chart object where as first parameter we pass in a selector
// that is resolving to our chart container element. The Second parameter
// is the actual data object.
new Chartist.Line('.ct-chart', data);
Creating a chart with fixed dimensions
In order to create a simple line chart with fixed width and height you only need to have a container element and initialize Chartist.js on it. Give the container the class ct-chart so that it will get the default styles (if you don't use your own classes).
var data = {
// A labels array that can contain any sort of values
labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
// Our series array that contains series objects or in this case series data arrays
series: [
[5, 2, 4, 2, 0]
]
};
// As options we currently only set a static size of 300x200 px. We can also omit this and use aspect ratio containers
// as you saw in the previous example
var options = {
width: 300,
height: 200
};
// Create a new line chart object where as first parameter we pass in a selector
// that is resolving to our chart container element. The Second parameter
// is the actual data object. As a third parameter we pass in our custom options.
new Chartist.Line('.ct-chart', data, options);
More than one chart on my page?
The example above uses the chartist default class to select the element where the chart should be created. This class is important for applying the right styles in the CSS of Chartist. If you need to create individual charts on one page, you should use IDs to initialize them separately.
<div class="ct-chart ct-golden-section" id="chart1"></div>
<div class="ct-chart ct-golden-section" id="chart2"></div>
<script>
// Initialize a Line chart in the container with the ID chart1
new Chartist.Line('#chart1', {
labels: [1, 2, 3, 4],
series: [[100, 120, 180, 200]]
});
// Initialize a Line chart in the container with the ID chart2
new Chartist.Bar('#chart2', {
labels: [1, 2, 3, 4],
series: [[5, 2, 8, 3]]
});
</script>
The configuration of your chart
Chartist.js is built very flexible and almost everything within your charts can be configured. In the default settings (that you can check in the API Documentation) you'll get some predefined defaults applied to your charts.
You can always override the default settings of your charts by passing in a configuration object at creation time.
// Our labels and three data series
var data = {
labels: ['Week1', 'Week2', 'Week3', 'Week4', 'Week5', 'Week6'],
series: [
[5, 4, 3, 7, 5, 10],
[3, 2, 9, 5, 4, 6],
[2, 1, -3, -4, -2, 0]
]
};
// We are setting a few options for our chart and override the defaults
var options = {
// Don't draw the line chart points
showPoint: false,
// Disable line smoothing
lineSmooth: false,
// X-Axis specific configuration
axisX: {
// We can disable the grid for this axis
showGrid: false,
// and also don't show the label
showLabel: false
},
// Y-Axis specific configuration
axisY: {
// Lets offset the chart a bit from the labels
offset: 60,
// The label interpolation function enables you to modify the values
// used for the labels on each axis. Here we are converting the
// values into million pound.
labelInterpolationFnc: function(value) {
return '$' + value + 'm';
}
}
};
// All you need to do is pass your configuration as third parameter to the chart function
new Chartist.Line('.ct-chart', data, options);
Responsive sugar topping
Responsive web design is all based on media queries as you are probably already aware. Media queries are great and they help you to define media related conditions that you can use to apply different styles for different media.
Sometimes it's also required to have different behavior on certain media and it's possible that a specific component of your web site should behave in an other way on a small media than on a large one. Luckily there is window.matchMedia in your browser that comes to the rescue. With matchMedia it's possible to let your javascript react differently based on CSS3 media queries.
Responsive setting overrides
Configuring different chart behavior for various media is made simple with an override mechanism. The priority of the override mechanism is based on order of specification of the matching media queries.
The following example uses different label interpolations (to save some space) on small media as well as different spacing between the bars of the bar chart series. Resize your browser window to see the effect.
var data = {
labels: ['Jan', 'Feb', 'Mar', 'Apr', 'Mai', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
series: [
[5, 4, 3, 7, 5, 10, 3, 4, 8, 10, 6, 8],
[3, 2, 9, 5, 4, 6, 4, 6, 7, 8, 7, 4]
]
};
var options = {
seriesBarDistance: 15
};
var responsiveOptions = [
['screen and (min-width: 641px) and (max-width: 1024px)', {
seriesBarDistance: 10,
axisX: {
labelInterpolationFnc: function (value) {
return value;
}
}
}],
['screen and (max-width: 640px)', {
seriesBarDistance: 5,
axisX: {
labelInterpolationFnc: function (value) {
return value[0];
}
}
}]
];
new Chartist.Bar('.ct-chart', data, options, responsiveOptions);
Cross-browser support
For IE9 you need to use a matchMedia polyfill. You should take a look at
Paul Irish's matchMedia polyfill. Make sure you include matchMedia.js as well as matchMedia.addListener.js as always both are needed to polyfill the full specification of window.matchMedia.
Different configuration for different series
Chartist also allows you to add specific configuration overrides for your series. This is useful if you want to combine different looks for your series on the same chart.
You can even take this one step further by again overriding your series configuration in some responsive settings overrides. This sounds complicated but it actually is very simple. Check the example code with inline comments below to see how easy it is.
var chart = new Chartist.Line('.ct-chart', {
labels: ['1', '2', '3', '4', '5', '6', '7', '8'],
// Naming the series with the series object array notation
series: [{
name: 'series-1',
data: [5, 2, -4, 2, 0, -2, 5, -3]
}, {
name: 'series-2',
data: [4, 3, 5, 3, 1, 3, 6, 4]
}, {
name: 'series-3',
data: [2, 4, 3, 1, 4, 5, 3, 2]
}]
}, {
fullWidth: true,
// Within the series options you can use the series names
// to specify configuration that will only be used for the
// specific series.
series: {
'series-1': {
lineSmooth: Chartist.Interpolation.step()
},
'series-2': {
lineSmooth: Chartist.Interpolation.simple(),
showArea: true
},
'series-3': {
showPoint: false
}
}
}, [
// You can even use responsive configuration overrides to
// customize your series configuration even further!
['screen and (max-width: 320px)', {
series: {
'series-1': {
lineSmooth: Chartist.Interpolation.none()
},
'series-2': {
lineSmooth: Chartist.Interpolation.none(),
showArea: false
},
'series-3': {
lineSmooth: Chartist.Interpolation.none(),
showPoint: true
}
}
}]
]);