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.
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.
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 |
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 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.
This is an inline bar chart: It can appear within a paragraph.
<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>
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.
<div class="barChart" data-chartData="[ {y:[30,100,170,80,120,70,150,20,60]} ]"></div>
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
.
<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>
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.
<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>
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.
<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>
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.
<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>
<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>
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="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>
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.
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. |
<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>
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.
<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>
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.
<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>
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.
<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>
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="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>
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 dataset like the initial state of the demo, you must define
the maxX
option, otherwise the result will be an error.
Choose the data refresh rate in milliseconds:
<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>
VM UI Framework is created, owned, maintained by Virtuosi Media, Inc. © 2012-2013.