Overview

Bar charts should be used to compare many items in multiple categories to each other.

The bar charts that you can create with this plugin are highly customizable, can be animated, updated dynamically, and feature options for histograms and pyramid charts. Find out more below.

Return to top

Usage

To create an bar chart, assign a class of barChart 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 bar 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', ...]
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
histogram Removes the gap between columns or bars to create a histogram. false true, false
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
pyramid Turns a bar chart with exactly 2 data series, one with all positive values and the other with all negative values, into a pyramid 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
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

Inline bar 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 bar chart: It can appear within a paragraph.

Show Code

<p>This is an inline bar chart: <span class="inlineBarChart" data-chartData="[
{x:[40,80,60,20,50,30]}
]"></span> It can appear within a paragraph.</p>

Return to top

Default

This is the default bar chart, with no options enabled. It expands to the full width of its container and shows data only. The x-axis data is not necessary.

Demo

Show Code

<div class="barChart" data-chartData="[
{y:[30,100,170,80,120,70,150,20,60]}
]"></div>

Return to top

Histograms

For bar charts with single data sets, you may wish to remove the gaps between the bars to create a histogram. To do so, set the histogram option to true.

Demo

Show Code

<div class="barChart" data-chartData="[
	{
		x:[0,1,6,3,17,12,24,38,15,87,75,45,23,12,73,17,45,87,99,34,20]
	}
]"

data-chartOptions="{
	histogram: true
}"></div>

Return to top

Axis Lines, Ticks, & 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.

Note Chart text may not be perfect on mobile-sized screens, so choose what information you display carefully.

Demo

Show Code

<div class="barChart" data-chartData="[
	{x:[6,24,38,15,87,75,45,23,12,73,87,99,34,20]}
]"

data-chartOptions="{
	showAxisLabels: true, 
	showAxisLines: true, 
	showTicksY: true, 
	showTicksX: true,
	showIntervalLabels: true,
	showTitle: true,
	title: 'Axis Lines, Ticks, & Labels',
	maxX: 100
}"></div>

Return to top

Custom Interval Labels

Custom interval labels can be added using the xLabels and yLabels options, which both accept an array of strings as a value. The number of strings in the yLabels array must match the number of data points in each data set.

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 If you want to skip a label, use null in place of any string in the label array.

Demo

Show Code

<div class="barChart" data-chartData="[
	{y:[30,100,170]},
	{y:[80,120,70]},
	{y:[20,60,30]}
]"

data-chartOptions="{
	showAxisLabels: true, 
	showAxisLines: true, 
	showTicksY: true, 
	showTicksX: true,
	showIntervalLabels: true,
	showTitle: true,
	title: 'Custom Labels',
	maxX: 200,
	yLabels: ['Bob', 'John', 'Sue']
}"></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 dataset 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 dataset 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="barChart" data-chartData="[
	{x:[38,15,87,75,45,23,12,73,17,45,87]},
	{x:[36,25,47,75,40,63,22,43,10,46,68]}
]"

data-chartOptions="{
	showAxisLabels: true, 
	showAxisLines: true, 
	showTicksY: true, 
	showTicksX: true,
	showIntervalLabels: true,
	showTitle: true,
	showKey: true,
	title: 'Bottom Key',
	maxX: 100
}"></div>
Demo

Show Code

<div class="barChart" data-chartData="[
	{x:[38,45,23,12,73,17,45,87]},
	{x:[36,25,47,75,43,10,46,68]}
]"

data-chartOptions="{
	showAxisLabels: true, 
	showAxisLines: true, 
	showTicksY: true, 
	showTicksX: true,
	showIntervalLabels: true,
	showTitle: true,
	showKey: true,
	keyPosition: 'right',
	title: 'Right Key',
	maxX: 100
}"></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="barChart" data-chartData="[
	{x:[87,75,45,23]},
	{x:[23,15,65,33]}
]"

data-chartOptions="{
	showAxisLabels: true, 
	showAxisLines: true, 
	showTicksY: true, 
	showTicksX: true,
	showIntervalLabels: true,
	showTitle: true,
	showKey: true,
	title: 'Grid Lines',
	showGridX: true,
	showGridY: true,
	maxX: 100
}"></div>

Return to top

Chart Tips

The tips for Data Set 1 in the demo are custom text, whereas the tips for Data Set 2 and Data Set 3 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 dataset.
Demo

Show Code

<div class="barChart" data-chartData="[
	{x:[1,6,3,17,12]},
	{x:[4,9,10,14,3]},
	{x:[17,2,7,15,8]}
]"

data-chartOptions="{
	showAxisLabels: true, 
	showAxisLines: true, 
	showTicksY: true, 
	showTicksX: true,
	showIntervalLabels: true,
	showTitle: true,
	showKey: true,
	title: 'Chart Tips',
	showGridX: true,
	showGridY: true,
	showTips: true,
	tipText: ['This is a custom tip. The value for the {xAxis} is: {x}'],
	maxX: 20,
	xInterval: 5 
}"></div>

Return to top

Negative Values & Custom Ranges

Using the minX and maxX options, you can override the default behavior and give your chart custom ranges.

Note Because of the way column charts are animated, you should avoid using animation for column charts with negative numbers.

Demo

Show Code

<div class="barChart" data-chartData="[
		{x:[1,6,3,-17,-15,87,75,-45,94]},
		{x:[12,37,34,-36,25,47,75,-40,63]}
	]"
	
	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,
		minX: -50,
		maxX: 100
}"></div>

Return to top

Pyramid Charts

To create a pyramid chart, use exactly two data sets, one with all negative values and the other will all positive values. Then, set the pyramid option to true and use both the minX and maxX to set the x-axis range to equal positive and negative spans.

Note Avoid using animation for pyramid charts.

Demo

Show Code

<div class="barChart" data-chartData="[
		{x:[-5,-6,-13,-17,-15,-87,-75,-45,-94]},
		{x:[12,37,34,36,25,47,75,40,63]}
	]"
	
	data-chartOptions="{
		showAxisLabels: true, 
		showAxisLines: true, 
		showTicksY: true, 
		showTicksX: true,
		showIntervalLabels: true,
		showTitle: true,
		showKey: true,
		title: 'People Who Like Vegetables',
		showGridX: true,
		showTips: true,
		tipText: [
			'{x}% of men, ages {y}, like vegetables', 
			'{x}% of women, ages {y}, like vegetables'
		],
		dataLabels: ['Men', 'Women'],
		xAxisLabel: 'Percent (%) Who Like Vegetables',
		xLabels: ['100', '75', '50', '25', '0', '25', '50', '75', '100'],
		yAxisLabel: 'Age (years)',
		yLabels: ['0-10', '11-20', '21-30', '31-40', '41-50', '51-60', '61-70', '71-80', '81+'],
		yLabelWidthPercentage: 8,
		minX: -100,
		maxX: 100,
		histogram: true,
		pyramid: true
}"></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 dataset.

Demo

Show Code

<div class="barChart" data-chartData="[
		{x:[0.3,0.1,0.6,0.45,0.75,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: 0.2,
		maxX: 1,
		decimalPrecisionX: 1,
		showTips: true
}"></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="animatedBarChart" class="columnChart" data-chartData="[
	{x:[3,17,12,24,73,87,99,34,20]},
	{x:[23,15,25,47,75,43,10,46,60]}
]"

data-chartOptions="{
	showAxisLabels: true, 
	showAxisLines: true, 
	showTicksY: true, 
	showTicksX: true,
	showIntervalLabels: true,
	showTitle: true,
	showKey: true,
	title: 'Animated Chart',
	showGridX: true,
	showGridY: true,
	showPoints: true,
	showTips: true,
	tipText: ['This is a custom tip. The value for the {xAxis} is: {x}'],
	animate: true,
	maxX: 100 
}"></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();
			$('animatedBarChart').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 dataset like the initial state of the demo, you must define the maxX option, otherwise the result will be an error.

Demo

Choose the data refresh rate in milliseconds:

Show Code

<div id="dynamicBarChart" class="columnChart" data-chartData=""

data-chartOptions="{
	showAxisLabels: true, 
	showAxisLines: true, 
	showTicksY: true, 
	showTicksX: true, 
	showIntervalLabels: true,
	showTitle: true,
	title: 'Dynamic Data Demo',
	showGridY: true,
	showAreaLines: true,
	maxX: 100,
	histogram: true
}"></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 xValue = Number.random(0, 100);
			var data = JSON.decode($('dynamicBarChart').getData('chartData'));

			if (!data){
				data = [{x: [xValue]}];
			} else {
				data[0].x.unshift(xValue)
				if (data[0].x.length > 10){
					data[0].x.splice(10, 1);
				} 
			}

			$('dynamicBarChart').setData('chartData', JSON.encode(data));
			$('dynamicBarChart').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();
			$('dynamicBarChart').setData('chartData', '');
			$('dynamicBarChart').fireEvent('updateChart');
		});
		
		$('dataSpeed').addEvent('change', function(){
			if ($('dataToggle').get('text') == 'Stop Data'){
				clearInterval(timer);
				timer = update.periodical(this.get('value').toInt());
			}
		});
	});
</script>

Return to top

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