Area Charts

Code
Demos

Overview

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.

Return to top

Usage

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.

Return to top

Options

Chart Options
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

Return to top

Events

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.

Return to top

Demos

Inline Area Chart

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.

Demo

This is an inline area chart: It can appear within a paragraph.

Show Code

<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>

Return to top

Default

This is the default area chart, with no options enabled. It expands to the full width of its container and shows data only.

Demo

Show Code

<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>

Return to top

Axis & Labels

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.

Demo

Show Code

<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>

Return to top

Interactive Keys

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.

Demo

Show Code

<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>
Demo

Show Code

<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>

Return to top

Grid Lines

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.

Demo

Show Code

<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>

Return to top

Lines, Points & Tips

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.

Tip Text Placeholders
Placeholders
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.
Demo

Show Code

<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>

Return to top

Negative Values & Custom Ranges

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.

Demo

Show Code

<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>

Return to top

Decimal Values & Custom Intervals

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.

Demo

Show Code

<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>

Return to top

Dates

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.

Date Formatting

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.

Troubleshooting

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.

Demos

Show Code

<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>

Show Code

<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>

Return to top

Animation

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.

Demo

Refresh Animation

Show Code

<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>

Return to top

Dynamic Data

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.

Empty Datasets

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.

Demo

Choose the data refresh rate in milliseconds:

Show Code

<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>

Return to top

Want to continue the tour?

VM UI Framework is created, owned, maintained by Virtuosi Media, Inc. © 2012-2013.