Area charts should be used to track one or more sets of data over time or to compare multiple sets of data. Area charts are similar in purpose to line charts, but provide more visual emphasis.
The area charts that you can create with this plugin are highly customizable, can be animated, updated dynamically, and feature lines, data points, and tooltips. Find out more below.
To create an area chart, assign a class of areaChart
to a div
element.
Data and options are assigned via the data-chartData
and data-chartOptions
attributes, respectively.
The data-chartData
attribute takes an array of JSON objects as its value, with each
object containing x and y keys with array values containing numerical data
points. Charts with dates along the x-axis will ignore the x key-value pair, so for those charts,
its possible to omit the x-axis information.
Chart options passed through the data-chartOptions
attribute must be contained in a
single-level JSON object, with each option key corresponding to a value. It's not necessary to
use the data-chartOptions
attribute if you only want to have the default chart. All of
the options relevant to area charts are detailed below.
Chart Options | |||
---|---|---|---|
Option | Description | Default Value | Values |
animate |
Animates the chart. | false |
true , false |
animationDuration |
The duration of the chart animation in seconds. | 1 |
Any positive number |
axisColor |
The hex color of the axis lines. | #333 |
Any hex color code as a string |
aspectRatio |
The aspect ratio of the entire chart area, including labels and keys. | [16, 9] |
An array of 2 positive integers [x, y] |
colors |
The hex colors for each series of chart data. | ['#058DC7', '#A006C7', '#C7062D', '#06C740',
'#C7A006', '#EEE', '#CCC', '#999', '#666', '#333', '#000'] |
An array of hex codes [color1, color2, ...] |
dataLabels |
Labels for each series of data, will also show in the key. If no labels are provided, labels will be 'Series 1', 'Series 2', etc. | [] |
An array of strings equal to the number of series ['Label 1',
'Label 2', ...] |
dateEnd |
Sets the end date for a time-based chart.
xAxisIsDate must be enabled. |
null |
'now' or any date string |
dateFormat |
Formats the date by replacing placeholders in a string.
xAxisIsDate must be enabled. |
'%b %d' |
A string of any combination of options from the MooTools Date Object |
dateIntervalUnit |
Sets the inverval unit for a date.
xAxisIsDate must be enabled. |
'day' |
'year' , 'month' , 'week' ,
'day' , 'hour' , 'minute' , 'second' ,
'ms'
|
dateIntervalValue |
Sets the interval value for a date.
xAxisIsDate must be enabled. |
1 |
Any positive integer |
dateStart |
Sets the start date for a time-based chart.
xAxisIsDate must be enabled. |
null |
'now' or any date string |
decimalPrecisionX |
The number of decimal places shown on x-axis interval labels or pie tips; does not affect placement or other tip types. | 0 |
0 or any positive integer |
decimalPrecisionY |
The number of decimal places shown on y-axis interval labels; does not affect placement or any tips. | 0 |
0 or any positive integer |
gridColor |
The hex color of the grid lines. | '#DDD' |
Any hex color string |
keyPosition |
The position of the key. The showKey option must
also be enabled. |
'bottom' |
'top' , 'bottom' , 'left' ,
'right' |
keyWidthPercentage |
The width percentage of the key in relation to the entire chart area, applicable only for left and right key positions. | 12 |
Any positive integer |
maxX |
The maximum value of the x-axis. | null |
Any number |
maxY |
The maximum value of the y-axis. | null |
Any number |
minX |
The minimum value of the x-axis. | 0 |
Any number |
minY |
The minimum value of the y-axis. | 0 |
Any number |
showAreaLines |
Toggles a line chart overlay on an area chart. | false |
true , false |
showAxisLabels |
Toggles both the x and y axis labels. | false |
true , false |
showAxisLines |
Toggles both the x and y axis lines. | false |
true , false |
showGridX |
Toggles the x-axis grid lines. | false |
true , false |
showGridY |
Toggles the y-axis grid lines. | false |
true , false |
showIntervalLabels |
Toggles interval labels on both axises. | false |
true , false |
showIntervalLabelsX |
Toggles interval labels on the x-axis. | false |
true , false |
showIntervalLabelsY |
Toggles interval labels on the y-axis. | false |
true , false |
showKey |
Toggles the chart key. | false |
true , false |
showPoints |
Toggles individual data points for area and line charts. | false |
true , false |
showTicksX |
Toggles tick marks along the x-axis. | false |
true , false |
showTicksY |
Toggles tick marks along the y-axis. | false |
true , false |
showTips |
Toggles tooltips for all charts. Line charts and area charts
must have showPoints enabled for tips to show. |
false |
true , false |
showTitle |
Toggles the chart title. | false |
true , false |
textColor |
The color of all text in the chart. | "#000" |
Any hex color string |
title |
The title of the chart. | "Untitled Chart" |
Any string |
tickColor |
The color of all tick marks. | "#333" |
Any hex color string |
tipText |
An array of HTML text strings to customize the tip text, one string for each series. Placeholders in the string (surrounded by curly braces {}) can be replaced by values or labels from the chart. Placeholders options include: {x}, {y}, {xAxis}, {yAxis}, {piePercent} and {label}. | [] |
An array of HTML strings with placeholders, one string for each series |
xAxisLabel |
The label for the x-axis. | "x-axis" |
Any string |
xInterval |
The interval for the x-axis. | 25 |
Any positive number |
xAxisIsDate |
Toggles the date options for a chart. Any coordinate values
for the x-axis entered in the data-chartData attribute will be
ignored. |
false |
true , false |
xLabels |
An array of labels for the x-axis matching the number of
intervals. If no labels are entered, the chart will default to using numbers. To
skip labels for an interval, use null as a placeholder in the array. |
[] |
An array of any combination of numbers, strings, or nulls matching the number of intervals |
yAxisLabel |
The label for the y-axis. | "y-axis" |
Any string |
yInterval |
The interval for the y-axis. | 25 |
Any positive number |
yLabelWidthPercentage |
The width percentage (in relation to the entire chart area) of y interval labels, if they are enabled. | 5 |
Any positive number |
yLabels |
An array of labels for the y-axis matching the number of
intervals. If no labels are entered, the chart will default to using numbers. To
skip labels for an interval, use null as a placeholder in the array. |
[] |
An array of any combination of numbers, strings, or nulls matching the number of intervals |
Each chart type has an updateChart
event, which allows the chart to be updated
dynamically. The event is bound to the chart container element and can be fired using MooTools'
fireEvent
method.
New data can be passed directly to the chart via fireEvent
. If no new data is passed
through fireEvent
, then the plugin will pull the data and options from the data
attributes.
Note When the updateChart
event is fired, the plugin
will rerender the chart completely.
Examples of how to use the updateChart
event can be found in the
Dynamic Data example.
Inline area charts are small charts that can appear inline within the context of a block of text or other inline elements. Note Because inline charts are so small, they should generally only be used with a single data set and without many of the visual chart features enabled. Keep inline charts simple.
This is an inline area chart: It can appear within a paragraph.
<p>This is an inline area chart: <span class="inlineAreaChart" data-chartData="[{ x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], y:[0,1,6,3,17,12,24,38,15,87,75,45,23,12,73,17,45,87,99,34,20] }]"></span> It can appear within a paragraph.</p>
This is the default area chart, with no options enabled. It expands to the full width of its container and shows data only.
<div class="areaChart" data-chartData="[ { x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], y:[0,1,6,3,17,12,24,38,15,87,75,45,23,12,73,17,45,87,99,34,20] }, { x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], y:[23,15,65,33,37,32,34,36,25,47,75,40,63,22,43,10,46,68,69,68,60] } ]"></div>
In this example, the title, labels, ticks, and axis lines have all been enabled. Each of those elements can be toggled separately through the options object.
If your labels are longer, you can specify the width of the area used for labels along the
y-axis using the yLabelWidthPercentage
option. The default value for
yLabelWidthPercentage
is 5% of the total width of the chart canvas area, but
the option accepts any positive integer value between 1-100.
Note Chart text may not be perfect on mobile-sized screens, so choose what information you display carefully.
<div class="areaChart" data-chartData="[ { x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], y:[0,1,6,3,17,12,24,38,15,87,75,45,23,12,73,17,45,87,99,34,20] }, { x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], y:[23,15,65,33,37,32,34,36,25,47,75,40,63,22,43,10,46,68,69,68,60] } ]" data-chartOptions="{ showAxisLabels: true, showAxisLines: true, showTicksY: true, showTicksX: true, showIntervalLabels: true, showTitle: true, title: 'Axis & Labels' }"></div>
The keys in the charts plugin are all interactive. Clicking on the key text or color square will toggle the visibility of that series in the graph.
Keys can appear in four different positions: top, bottom, left, or right, with a default position of bottom. Choose the appropriate key position based on the length and number of your series labels.
Note The width of the left and right key
positions can be determined using the keyWidthPercentage
option, which
defaults to 15%. Because cross-browser support for SVG text-wrapping isn't particularly
fantastic, you'll need to use this option for especially longer labels.
<div class="areaChart" data-chartData="[ { x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], y:[0,1,6,3,17,12,24,38,15,87,75,45,23,12,73,17,45,87,99,34,20] }, { x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], y:[23,15,65,33,37,32,34,36,25,47,75,40,63,22,43,10,46,68,69,68,60] } ]" data-chartOptions="{ showAxisLabels: true, showAxisLines: true, showTicksY: true, showTicksX: true, showIntervalLabels: true, showTitle: true, showKey: true, title: 'Bottom Key' }"></div>
<div class="areaChart" data-chartData="[ { x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], y:[0,1,6,3,17,12,24,38,15,87,75,45,23,12,73,17,45,87,99,34,20] }, { x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], y:[23,15,65,33,37,32,34,36,25,47,75,40,63,22,43,10,46,68,69,68,60] } ]" data-chartOptions="{ showAxisLabels: true, showAxisLines: true, showTicksY: true, showTicksX: true, showIntervalLabels: true, showTitle: true, showKey: true, keyPosition: 'right', title: 'Right Key' }"></div>
Grid lines can be added to the chart as well, with granular control over both the X
and Y lines through the showGridX
and showGridY
options.
Grid line color is set through the gridColor
option.
<div class="areaChart" data-chartData="[ { x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], y:[0,1,6,3,17,12,24,38,15,87,75,45,23,12,73,17,45,87,99,34,20] }, { x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], y:[23,15,65,33,37,32,34,36,25,47,75,40,63,22,43,10,46,68,69,68,60] } ]" data-chartOptions="{ showAxisLabels: true, showAxisLines: true, showTicksY: true, showTicksX: true, showIntervalLabels: true, showTitle: true, showKey: true, title: 'Grid Lines', showGridX: true, showGridY: true }"></div>
The area chart can display a line overlay from point to point, as well as individual data
points using the showAreaLines
and showPoints
options.
The tips for Data Set 1 in the demo are custom text, whereas the tips for Data
Set 2 are the default tips. Tip text can be customized per data set and is set via the
tipText
option.
The tipText
option's value should be an array, with custom text as a series of
strings in the same order as the data sets. The string can take HTML and also has special
placeholders that will be replaced automatically.
String | Replacement |
---|---|
{x} | The x-cordinate value. |
{y} | The y-cordinate value. |
{xAxis} | The name of the x-axis. |
{yAxis} | The name of the y-axis. |
{label} | The name of the series. |
<div class="areaChart" data-chartData="[ { x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], y:[0,1,6,3,17,12,24,38,15,87,75,45,23,12,73,17,45,87,99,34,20] }, { x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], y:[23,15,65,33,37,32,34,36,25,47,75,40,63,22,43,10,46,68,69,68,60] } ]" data-chartOptions="{ showAxisLabels: true, showAxisLines: true, showTicksY: true, showTicksX: true, showIntervalLabels: true, showTitle: true, showKey: true, title: 'Lines, Points, & Tips', showGridX: true, showGridY: true, showAreaLines: true, showPoints: true, showTips: true, tipText: ['This is a custom tip. The value for the {xAxis} is: {x}'] }"></div>
By default, the chart area will expand to accomodate all of the data with the largest view possible while still making the chart legible. Negative values in your series will add a one interval padding to the bottom of your chart below your lowest value, while charts with no negative numbers will not add the bottom interval. All charts add a one interval padding to the top of the chart. This is done for asthetic purposes, adding visual whitespace to the chart.
Using the maxX
, minX
, maxY
, and minY
options, you can override the default behavior and give your chart custom ranges.
Note Because of the way area charts are animated, you should avoid using animation for area charts with negative numbers.
<div class="areaChart" data-chartData="[ { x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], y:[0,1,6,3,-17,12,24,38,-15,87,75,45,23,12,73,17,-45,87,99,34,20] }, { x:[-25,-20,-15,-10,-5,0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], y:[0,12,80,22,30,23,15,65,33,37,32,34,-36,25,47,75,-40,63,22,43,10,46,68,69,68,60] } ]" data-chartOptions="{ showAxisLabels: true, showAxisLines: true, showTicksY: true, showTicksX: true, showIntervalLabels: true, showTitle: true, showKey: true, title: 'Negative Values & Custom Ranges', showGridX: true, showGridY: true, maxX: 150, minX: -50 }"></div>
Decimal values can be used in any chart, but in most cases, you will probably want to adjust
the intervals along at least one of the axises. To do so, use the xInterval
and yInterval
options to establish custom intervals.
By default, the interval labels will show only integers, so any decimal interval labels will
be rounded to the nearest integer. To show decimal interval labels, use the
decimalPrecisionX
and decimalPrecisionY
options to specify the
number of decimal places to be shown. Note This will only
affect the interval labels; the data points and tips will display the full number as
specified in the series.
<div class="areaChart" data-chartData="[ { x:[0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20], y:[0,0.3,0.1,0.6,0.45,0.1,0.3,0.1,0.8,0.45,0,0.3,0.1,0.6,0.45,0.1,0.3,0.1,0.6,0.45,0.2] } ]" data-chartOptions="{ showAxisLabels: true, showAxisLines: true, showTicksY: true, showTicksX: true, showIntervalLabels: true, showTitle: true, title: 'Decimal Values & Custom Intervals', showGridX: true, showGridY: true, xInterval: 4, yInterval: 0.2, decimalPrecisionY: 1, showPoints: true, showAreaLines: true }"></div>
Charts can make use of dates along along the x-axis. When using dates, it is not necessary
to enter the x-coordinate in the series (if you do, it will be ignored). To enable dates along
the x-axis, set the xAxisIsDate
option to true
.
The date range is set using the dateStart
and dateEnd
options,
both of which accept any date string accepted by the default JavaScript
Date
object. The default value for both options is the current date and time, so at least
one option will need to be specified.
Date intervals are controlled by two options: dateIntervalUnit
and
dateIntervalValue
. The default value for the dateIntervalUnit
option is day
, but other options include:
year
month
week
day
hour
minute
second
ms
The dateIntervalValue
option controls the frequency of the interval in the
chosen date unit. The default value is 1.
The date label format is highly customizable and can feature almost any unit of time in a
custom string. The format is set via the dateFormat
option. All date
replacement strings must be preceded by the percent sign, %
. The replacement
string formats can be found in the MooTools More
Date.format method
documentation.
If the labels or values are displaying incorrectly, make sure that you have a date range that corresponds to at least the number of data points. If you come up short, the chart will be off.
<div class="areaChart" data-chartData="[ {y:[0,1,6,3,17,12,24,38,15,87,75,45,23,12,73,17,45,87,99,34,20]}, {y:[23,15,65,33,37,32,34,36,25,47,75,40,63,22,43,10,46,68,69,68,60]} ]" data-chartOptions="{ showAxisLabels: true, showAxisLines: true, showTicksY: true, showTicksX: true, showIntervalLabels: true, showTitle: true, showKey: true, title: 'Days', showGridX: true, showGridY: true, showPoints: true, showAreaLines: true, showTips: true, xAxisIsDate: true, dateStart: '1/1/2012', dateEnd: '1/21/2012', dateIntervalValue: 3 }"></div>
<div class="areaChart" data-chartData="[ {y:[0,1,6,3,17,12,24,38,15,87,75,45,23,12,73,17,45,87,99,34,20]}, {y:[23,15,65,33,37,32,34,36,25,47,75,40,63,22,43,10,46,68,69,68,60]} ]" data-chartOptions="{ showAxisLabels: true, showAxisLines: true, showTicksY: true, showTicksX: true, showIntervalLabels: true, showTitle: true, showKey: true, title: 'Years', showGridX: true, showGridY: true, showPoints: true, showAreaLines: true, showTips: true, xAxisIsDate: true, dateFormat: '%Y', dateStart: '1/1/1993', dateEnd: '1/1/2013', dateIntervalUnit: 'year', dateIntervalValue: 3 }"></div>
The chart can be animated by setting the animate
option to true
.
The length of the animation can also be controlled with the animationDuration
option, which defaults to a 1 second animation.
Note Animations do not currently work in Internet Explorer
as it does not support declarative animations. The chart will simply ignore the
animate
option and display a static chart in Internet Explorer.
Animation has also been disabled in Safari until further testing can be performed and a fix can be found. A static chart will also be displayed for Safari.
<div id="animatedAreaChart" class="areaChart" data-chartData="[ { x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], y:[0,1,6,3,17,12,24,38,15,87,75,45,23,12,73,17,45,87,99,34,20] }, { x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], y:[23,15,65,33,37,32,34,36,25,47,75,40,63,22,43,10,46,68,69,68,60] } ]" data-chartOptions="{ showAxisLabels: true, showAxisLines: true, showTicksY: true, showTicksX: true, showIntervalLabels: true, showTitle: true, showKey: true, title: 'Animated Chart', showGridX: true, showGridY: true, showAreaLines: true, showPoints: true, showTips: true, tipText: ['This is a custom tip. The <b>value</b> for the {xAxis} is: {x}'], animate: true }"></div> <p><a id="animateButton" class="infoButton" href="#">Refresh Animation</a></p> <script type="text/javascript"> window.addEvent('domready', function(){ $('animateButton').addEvent('click', function(e){ e.stop(); $('animatedAreaChart').fireEvent('updateChart'); }); }); </script>
The chart can be updated dynamically using data generated via script or retrieved via AJAX.
To update the chart, fire the updateChart
event on the chart container
element. New data can either be passed in as parameters via the fireEvent
function or you can choose to dynamically update the data-chartData
attribute and the data will be automatically detected when the updateChart
event is fired.
Notes When the updateChart
event is fired, the
entire chart is re-rendered. Animations should not be used with dynamic data with a high
refresh rate.
If you want to have an empty series like the initial state of the demo, you must define
both the maxX
and maxY
options, otherwise the result will be an
error.
Choose the data refresh rate in milliseconds:
<div id="dynamicAreaChart" class="areaChart" data-chartData="" data-chartOptions="{ showAxisLabels: true, showAxisLines: true, showTicksY: true, showTicksX: true, showIntervalLabels: true, showTitle: true, title: 'Dynamic Data Demo', showGridX: true, showGridY: true, showAreaLines: true, maxX: 100, maxY: 100 }"></div> <ul class="unlisted horizontal"> <li><a id="dataToggle" class="infoButton" href="#">Start Data</a></li> <li><a id="clearData" class="button" href="#">Clear Data</a></li> </ul> <p>Choose the data refresh rate in milliseconds:</p> <form> <input type="text" id="dataSpeed" name="dataSpeed" class="slider" data-range="10,1000" data-increment="10" data-start="500"> </form> <script type="text/javascript"> window.addEvent('domready', function(){ var update = function(){ var yValue = Number.random(0, 80); var data = JSON.decode($('dynamicAreaChart').getData('chartData')); if (!data){ data = [{x: [0], y: [yValue]}]; } else { data[0].y.push(yValue) if (data[0].y.length > 101){ data[0].y.splice(0, 1); } else { data[0].x.push(data[0].x.length); } } $('dynamicAreaChart').setData('chartData', JSON.encode(data)); $('dynamicAreaChart').fireEvent('updateChart'); }; var timer; $('dataToggle').addEvent('click', function(e){ e.stop(); if (this.get('text') == 'Start Data'){ this.set('text', 'Stop Data'); timer = update.periodical($('dataSpeed').get('value').toInt()); } else { this.set('text', 'Start Data'); clearInterval(timer); } }); $('clearData').addEvent('click', function(e){ e.stop(); $('dynamicAreaChart').setData('chartData', ''); update(); }); $('dataSpeed').addEvent('change', function(){ if ($('dataToggle').get('text') == 'Stop Data'){ clearInterval(timer); timer = update.periodical(this.get('value').toInt()); } }); }); </script>
VM UI Framework is created, owned, maintained by Virtuosi Media, Inc. © 2012-2013.