A Beginner’s Guide to Dojo Charting, Part 1 of 2

By on June 6, 2008 12:30 am

Welcome! If you are looking for a way to quickly and easily add great looking and functional charts and graphs to your web pages, you’ve found the right place. All you need is a tiny bit of JavaScript skills and a copy of Dojo.

In this two part guide, we look at how easy it is to get Dojo Charting up and running, and then examine in greater detail the options available for different looks for your charts. Today in Part 1, we start with a basic example and then examine all the options available in defining your plot type. Part 2 will cover the options available in defining the axes and data sets for your charts.

Let’s get started. Here is the code for a basic Dojo Chart, make sure you have the proper path to your dojo.js file:

Basic Charting

This source code produces the following simple chart.

Simple Chart

Looking at this we can see that most of the work in defining the chart is done in the addPlot(), addAxis(), and addSeries() functions. Today we will examine the addPlot() call, and Part 2 will cover the options for addAxis() and addSeries().

Got Plot?

The addPlot() call determines what type of chart you are going to produce, and there are a variety of options to select. Here are a few examples:

Some Chart Types

addPlot() accepts 2 parameters, a name and an arguments array. The name is important if you want to have more than 1 plot type on your chart, a concept we will cover shortly. The arguments array contains your options, and these may vary depending on the type of plot you use. Note that your choice of plot type may define appropriate default options.

Let’s examine our options. Type is the main option, and the default value is a basic line chart.

chart1.addPlot("default", {type: "Areas"});

Available 2D chart types include:

  • Areas – Area under data line(s) will be filled
  • Bars – Horizontal bars.
  • ClusteredBars – Horizontal bars with clustered data sets
  • ClusteredColumns – Vertical bars with clustered data sets
  • Columns – Vertical bars
  • Grid – For adding a grid layer to you chart
  • Lines – Basic line chart
  • Markers – Lines with markers
  • MarkersOnly – Markers, sans lines
  • Pie – Goes great with punch!
  • Scatter – Cooler name for MarkersOnly
  • Stacked – Data sets charted in relation to the previous data set.
  • StackedAreas – Stacked data sets with filled areas under chart lines
  • StackedBars – Stacked data sets with horizontal bars
  • StackedColumns – Stacked data sets with vertical bars
  • StackedLines – Stacked data sets using lines

If you choose any of the lines, areas or markers types you have 5 specific options. First up we have 3 switches, which are lines, areas, and markers. These are often defined by the plot type you choose, but can be changed to get your desired behavior. The lines option determines whether or not lines are used to connect your data points. If the areas type is selected, the area below your data line will be filled. The markers option will determine if markers are placed at your data points.

chart1.addPlot("default", {type: "StackedAreas", lines: true, areas: true, 
	markers: false});

There are also 2 graphical options, tension and shadows. Tension allows you to add some curve to the lines on you plot. By default this option is set to 0 which is off. I found 2-4 to be a good range for natural looking curves. For some crazy effects try setting this to values < 1 or negatives. Shadows allow you to add a shadow effect, and consists of an array of 3 parameters, dx, dy and dw, which represent the offset to the right, the offset down, and the width of the shadow line, respectively. You can use negative values for your dx and dy parameters to produce a shadow that is to the left or above your chart line.

chart1.addPlot(“default”, {type: “StackedLines”,tension:3, 
	shadows: {dx: 2, dy: 2, dw: 2}});

Bar and column graph types have 1 unique option: they will accept a gap parameter that determines the spacing between your bars or columns in pixels.

chart1.addPlot("default", {type: "Bars", gap: 5});

For any chart type that supports axes, you can also define custom names to your axes here. By default they are “x” and “y”, but this option becomes useful if you wish to have a chart with multiple plots and multiple axes.

chart1.addPlot("default", {type: "Bars", hAxis: "cool x", 
	vAxis: "super y"});

Pie charts are very different by nature, and have a separate list of parameters. I’ll leave it up to you to explore the parameters for the pie chart, from Pie.js:

defaultParams: {
	labels: true,
	ticks: false,
	fixed: true,
	precision: 1,
	labelOffset: 20,
	labelStyle: "default",      // default/rows/auto
	htmlLabels: true            // use HTML to draw labels
optionalParams: {
	font: "",
	fontColor: "",
	radius: 0

One other type with unique options is the grid. This plot type will draw grid lines along your tick marks and supports the following four boolean options to determine if lines will be displayed at the horizontal or vertical and major or minor axis tick marks. We will learn more about axes and look at a sample including the grid type in Part 2.

chart1.addPlot("default", {type: "Grid",
        hMajorLines: true, 
        hMinorLines: false,
        vMajorLines: true,
        vMinorLines: false});

Now, let’s go back to our starting example and spruce it up a bit. Let’s add a shadow, some curve to our line, and markers on our data points.

chart1.addPlot("default", {type: "Lines", markers: true, 
	tension:3, shadows: {dx: 2, dy: 2, dw: 2}});

And now our chart looks like this:

Some Chart Types

One last feature I’d like to touch on is adding multiple plots to the same chart. Multiple plots can be of differing types and can all be configured separately. Each plot you add with addPlot() will be layered behind the previous plot. In addition, plots can have their own axes or share them with other plots on the chart. Now, if we add an areas plot to our lines example, we can create the following effect.

var chart1 = new dojox.charting.Chart2D("simplechart");
chart1.addPlot("default", {type: "Lines"});
chart1.addPlot("other", {type: "Areas"});
chart1.addAxis("y", {vertical: true});
chart1.addSeries("Series 1", [1, 2, 2, 3, 4, 5, 5, 7]);
chart1.addSeries("Series 2", [1, 1, 4, 2, 1, 6, 4, 3], 
	{plot: "other", stroke: {color:"blue"}, fill: "lightblue"});

Some Chart Types

That’s all for today. Check back soon for Part 2 where we will cover the options available in the addAxes() and addSeries() calls.


  • Excellent tutorial, very good explanation of charting basics

  • One issue I’ve found is that setting the hAxis and vAxis parameters seems to stop the chart from renderering. e.g.

    var chart1 = new dojox.charting.Chart2D("simplechart");
        chart1.addPlot("default", {
    		hAxis: "X Axis",
    		vAxis: "V Axis",
    		type: "Bars", 
    		areas: true,
    		gap: 5
        chart1.addAxis("y", {vertical: true});
        chart1.addSeries("Series 1", [1, 2, 2, 3, 4, 5, 5, 7]);

    does not render, but take out the hAxis and vAxis parameters, and it renders just fine in FF2

  • Shane, you need to change the name on your addAxis calls to match the values for the hAxis and vAxis parameters.

    chart1.addAxis(”X Axis”);
    chart1.addAxis(”V Axis”, {vertical: true});

    I’ll be covering the addAxis() call in detail in part 2, which I hope to be able to get posted in the next few days.

  • The beginners guide is a good place to start.

    I have the following

    makeCharts = function(){
    	var chart1 = new dojox.charting.Chart2D("simplechart");
    	chart1.addPlot("default", {type: "Bars", hAxis:"X Axis", 
    		vAxis:"Y Axis", areas: true, gap: 10});
    	chart1.addAxis("X Axis");
    	chart1.addAxis("Y Axis", {vertical: true});
    	chart1.addSeries("Series 1", [1, 2, 2, 3, 4, 5, 5, 7]);

    The above does not render in Firefox.
    It renders in IE, but the horizontal bars don’t have a gap.

  • This is the second part of my example.

  • Oops, the DIV tags are not appearing in my comments.

    This a description of my DIV tag.

    I have a ContentPane in a DIV tag
    Then under that I have a TabContainer in a DIV tag
    The under that I have another ContentPane in a DIV tag
    The under that I have a DIV tag for the “simplechart” as in the example

  • It’s kind of working for me now in Firefox and in IE.

    But only when the DIV tag containing the id=”simplechart” is brought out of my structure [ContentPane–>TabContainer–>ContentPane–>DIV tag for chart]

    Looks like if its inside a ContentPane enclosed in a Tabcontainer which in itself is enclosed in a ContentPane, its not rendered in Firefox, either that or its rendered behind the TabContainer.

    Any help as to what Iam doing wrong or is it a bug in Dojo?

  • Hi Sishyan, can you please post a link to the full code? If it’s a bug, we’ll file a ticket in Dojo’s issue tracking system.

  • Hi Doug,

    I changed the names of the axes to match, and they still do not display. Is there another setting I need to enable axis labels?

    Looking at all demos/tests of the charts in dojo, none of them have labels, besides the Pie charts.



  • Hi Sishyan, the issue where you are not seeing a gap may be due to size. If the gap between lines would make the bar less then 1 pixel it seems to reset to 0 gap. Try increasing the height of the div or reducing the gap size. I’m not sure why a chart wouldn’t render inside a ContentPane.

  • Hi Shane, I think I may have misunderstood your earlier question. There is currently no direct way to display the axis titles, just labels on the tick marks, which can be customized. However, the event support in 1.2 includes axis information, maybe that could be useful. There was a post about it a week or so ago by Eugene. He also mentions that a Chart Legend Widget is in the works, which I suspect should allow you to display axis information. Here is his post: http://www.sitepen.com/blog/2008/05/27/dojo-charting-event-support-has-landed/

  • The first example doestn work for me
    what is wrong

  • never mind I made one work. I still don’t know how.

  • OK it was one of those invisible typos. Now all is good. WHere is part 2?

  • Hi Doug,

    Not being able to display axis labels is quite a large limitation – was it deliberate? Surely it couldn’t be difficult to implement. Was it an oversight?



  • Hi Dylan,

    I have pasted the codefragment here.


    The first one works fine, as the Chart DIV is outside the TabContainer.

    But the second fragment does not render.

  • Big thanks. Iam playing a little with dojo charting at moment. Your article was a great help for my first steps. I hope to see the second part, soon. 8-)

  • By the way, it works in IE,the chart inside contentpane in tab container, but not in firefox.

  • Hi Shane, I did some digging around and axis titles are on the to do list. They won’t make the 1.2 release, but they are on the list.

  • Pingback: SitePen Blog » A Beginner’s Guide to Dojo Charting, Part 2 of 2()

  • I wanted to recreate the effect of the chart2d test for sparklines, but when I use dojox.charting.Chart2D instead of dojox.charting.widget.Chart2D the charting engine still leaves room on the left and on the bottom for the axis labels (which I am not setting)

    I played with the axis and plot parameters for several hours and still no luck.

  • @Denilson: To make sure I understand correctly, are you comparing the results of http://archive.dojotoolkit.org/nightly/dojotoolkit/dojox/charting/tests/test_sparklines.html with a non-widget version of a Sparkline just using normal 2D charting? It sounds like a bug, just want to make sure I understand this correctly before I file a ticket on it.

  • @Dylan, your assumption is correct, my chart created with this snippet:

    sparkline = new dojox.charting.Chart2D(“sparkline”);
    sparkline.addPlot(“default”, { type: “Default”,
    lines: true,
    stroke: null,
    fill: null,
    margins: null,
    markers: false} );

    sparkline.addAxis(“x”, { min: 0,
    max: datesArray.length-1,
    majorTick: { length: 0},
    minorTick: { length: 0},
    minorTicks: false,
    microTicks: false,
    minorLabels: false,
    majorLabels: false});
    sparkline.addAxis(“y”, { vertical: true,
    majorTick: { length: 0},
    minorTick: { length: 0},
    minorTicks: false,
    microTicks: false,
    minorLabels: false,
    majorLabels: false});
    sparkline.addSeries(“Series A”, seriesArray);

    has quite a bit of padding (~50-70px) on both left and bottom sides. When I enable labels and ticks, they fit quite nicely in that buffer area. A cursory look through the Chart2D.js seems to confirm my assumption.

  • hey Denilson:

    The issue here is the margins. If you look at the sparklines demo page you’ll see that it explicitly sets margins:


    Like this:

    margins=”{ l: 0, r: 0, t: 0, b: 0 }”

    If you set the widget margins similarly you should get the same result. In the nightlies there’s also a new sparkline widget which makes this even easier:



  • Destroyer

    Hi, When is the Part2 of this tutorial coming out? I want to create a chart with live data, and want to be able to go back in history or zoom-in to any section. Is this possible be dojo? Thanks.

  • @Destroyer: Charting Part 2.

    Your other requests are possible, but would require some non-out-of-the-box work to make it happen. Free free to contact us if you want to explore engaging us to make that happen, or visit the IRC channel or Dojo forum to get additional community support (useful links to community support resources may be found at http://www.sitepen.com/labs/dojo.php .

  • David S.

    I am trying to implement a dynamic chart using dojox charting. I’ve built a very simple JavaScript file that defines the chart and propagates it with randomly generated data, much like the dynamic demo that comes packaged with dojox. My charting works fine, but after about 125 points are added to a plot, the plot browser starts to consume an excessive amount of memory and adding more than one plot to a webpage as I’m wanting to do is nearly impossible with as much memory as is being consumed.

    I first tried my implementation on the nightly build of dojo so that I could incorporate events, tooltips, etc. Suspecting the memory problems were resulting from the version of dojo I was using, I commented out the new features from my JavaScript and tried running it with the newest stable release of DOJO. That was not quite as laggy initially, but again, after 100 points or so, it started to really slow down the browser.

    I’m attaching just my JavaScript to this post in case anyone has a suggestion. This JavaScript implementation will fit my needs perfectly, but I need to figure out how to make it consume less browser resources. Ultimately I’m wanting to put ~6 plots with 1-4 data series per chart. Each data series will have about 200 points each. Is this feasible, or am I expecting too much of this application?


    // auto loaded modules
    // variable declarations
    var dialog;
    var chart, limit = 300, magnitude = 10;
    var signal1Series = [1];
    var target = 50;
    var usl_value = 80;
    var lsl_value = 20;
    var ucl_value = 60;
    var lcl_value = 40;
    // random number generator
    var randomValue = function(){
    	return (Math.random() * magnitude) + 40;
    // initialize the chart
    var makeObjects = function(){
    	chart = new dojox.charting.Chart2D("test");
    	chart.addAxis("x", {fixLower: "minor", fixUpper: "minor", natural: true});
          chart.addAxis("y", {vertical: true, min: 0, max: 100, majorTickStep: 5, minorTickStep: 1});
    	chart.addPlot("default", {type: "Default", lines:false, markers:true, tension:2});
    	// add limit and target lines
    	chart.addPlot("limits", {type: "Default", lines:true, markers: false, tension:3, shadows: {dx: 2, dy: 2, dw: 2}});
    	chart.addSeries("usl", [{x: 0, y: usl_value}, {x: signal1Series.length, y: usl_value}], {plot: "limits", stroke: {color:"red"}});
    	chart.addSeries("lsl", [{x: 0, y: lsl_value}, {x: signal1Series.length, y: lsl_value}], {plot: "limits", stroke: {color:"red"}});
    	chart.addSeries("ucl", [{x: 0, y: ucl_value}, {x: signal1Series.length, y: ucl_value}], {plot: "limits", stroke: {color:"yellow"}});
    	chart.addSeries("lcl", [{x: 0, y: lcl_value}, {x: signal1Series.length, y: lcl_value}], {plot: "limits", stroke: {color:"yellow"}});
    	chart.addSeries("ts",  [{x: 0, y: target}, {x: signal1Series.length, y: target}], {plot: "limits", stroke: {color:"green"}});
    	chart.addSeries("signal", signal1Series, {plot: "default", stroke: {color:"black"}, marker: "m-3,0 c0,-4 6,-4 6,0 m-6,0 c0,4 6,4 6,0"});
    	     function(evt) {
                      if(evt.type == "onclick") {
    	var anim2a = new dojox.charting.action2d.Magnify(chart, "default", {scale: 1.5});
    	var anim3b = new dojox.charting.action2d.Tooltip(chart, "default");
    	var anim2b = new dojox.charting.action2d.Highlight(chart, "default");
    	chart.addPlot("grid", {type: "Grid", hMinorLines: true});
          setInterval(function(){updateSignalData();}, 2000);
    	var legend = new dojox.charting.widget.Legend({chart: chart, horizontal: false}, "legend");
    // add data to signal series
    var updateSignalData = function(){	
    	if(signal1Series.length == limit) {
    		signal1Series.shift(); // remove first item from the array
    	chart.updateSeries("signal", signal1Series);
    // update target and limit lines
    var updateLines = function(length){
    	chart.updateSeries("usl", [{x: 0, y: usl_value}, {x: length, y: usl_value}]);
    	chart.updateSeries("lsl", [{x: 0, y: lsl_value}, {x: length, y: lsl_value}]);
    	chart.updateSeries("ucl", [{x: 0, y: ucl_value}, {x: length, y: ucl_value}]);
    	chart.updateSeries("lcl", [{x: 0, y: lcl_value}, {x: length, y: lcl_value}]);
    	chart.updateSeries("ts", [{x: 0, y: target}, {x: length, y: target}]);
    // use dojo to build all objects
  • Trevor

    Doug, Dylan, and the Dojo crew,

    Great Job on this tutorial and this graphing widget! After much arm twisting from Matt, I finally gave Dojo a try, and I am very impressed. Dojo is looking like a very suitable replacement for JQuery. The dojo.query feature is very nice. Keep up the good work and I suspect I will be filling out one of those contributors forms in the near future.

  • Sterling

    Thanks for this post! Keep the information about Dojo charts coming. There’s a big interest in this with the mapping and GIS community. For example, I am working on an example where a demographic chart appears when the user hovers the mouse over a county on a map. Hovering over a different county changes the chart.

  • @Sterling: I myself have the GIS background, and I want to see maps, and geo-coded charts in Dojo eventually. Stay tuned!

  • Inbar

    Not sure this is the right place to post this BUT – I am completely new to Dojo & looking mainly for UI capabilities including charting, drag & drop, resize, etc.
    My question regarding Dojo charting: I am looking for a reference to any info regarding chart events (if it is even available). Specifically, I am looking to capture user selection of chart elements (pie slice in a peichart; bar in a barchart) so that I can implement drill down type of behavior.
    Looking for some direction before I delve into sea of info and get lost…
    Thanks a bunch!!

  • Inbar

    I apologize; I think I was too quick to post this message (too much pressure to find solutions RIGHT NOW ;-)).
    I have found my info elsewhere. This is a good starting point, for others that may be interested in the same:

    As for this tutorial (as well as part 2) – I think it is great!

  • Travis

    The charting I see is fantastic. My only issue is documentation. While this tutorial is great, I need to implement a clustered bar/column chart and am not finding any direct examples of it. Has anyone done it? I’d love to copy your homework :-) I’m looking for something very simple…I need to compare 12 months of data to the 12 months of data the prior year in a clustered bar or column chart.

  • Pingback: 30 Essential Controls()

  • Pingback: Article about Dojo Charting « Rolf Kremer - Weblog()

  • Pingback: Chart in web pages | The symphony of information technology()

  • Lalit

    Hello friends,
    I am using pie charts of dojox.I am able to obtain the desired output by using the following :

    But i want to provide height andd width in %age terms at “300px” and “250px” places in above statement.
    So can anybody help me out in this regard.

    Thanks in advance.

  • shakel

    Hi Lalit,

    Hope you read this post.
    I too need to generate pie charts. Can you please let me know how were you able to do it? Or can you suggest me something.

    Thank you very much.

    am a beginner and this tutorial has been of great help…


  • shane


    I need to display 2 pie charts, one beside the other. I am trying to add 2 grids, but i think the 2nd pie chart is coming on top of the 1st. Can anyone please guide me to display these 2 charts besides each other.

    Thank you..

  • John


    The support for Axis Titles was talked about a year ago June. Has there been any update as to when they will be supported? It is definitely a very important feature to be able to say what the units are for each axis.


  • Kalle

    I kind of think this Dojo Charting sucks big time because it doesn’t work in IE. Why even bother to release it even then? Normal people who ain’t so computer savvy, almost 90 % of them uses Internet Explorer, and you don’t support them??? Why even bother to make this crap…
    The first thing to check for when building these widgets is to get them work in all browsers, and then check and proceed to the next item. You guys make me loose trust in dojo, or at least the crap called Dojox. Ain’t there some other way to build these charts than using SVG, Yahoo uses Flash or is it possible to do it in pure HTML? I would even use a product which was a lot simpler (in construction) (= in pure HTML and JS) but had FULL browser support. I have done before an img tag with an gif which I resize, and this kind of solution seems superior to Dojox because it works in all browsers… A solution based on that and making a widget on that would be nice…
    PS. All of DOJO I don’t think is not all bad, I actually use it so it must be good in some way.

  • Kalle, they do work in IE. They fall back on using VML or Silverlight for IE which doesn’t have SVG or Canvas natively… If something is not working for you, it’s a bug. Please let us know.

  • I want to display a bar graph with value on top of each bar, is this possible with DOJO’s charting API.

    Also, how can I create multicolor bar and provide an index what each color represents? Is there some ready made feature to implement this?

  • @Dylan I’m having exactly the same problem that Denilson reported: Using the API to create a sparkline the margins I specify aren’t being respected and it looks like it’s leaving a lot of space for axis labels I’m not using.

    I specify the margins like this:

    sp.addPlot(‘default’, {type: ‘Default’,
    lines: true,
    stroke: null,
    fill: null,
    margins: {l: 0, r: 0, t: 0, b: 0},
    markers: false});

  • David Votrubec

    The example works fine in standart browsers, but it causes IE8 to crash.
    But for some reason it works fine in IE6 on another machine…
    What do I need to do to run in IE7/8 ?

  • Anil

    Hi Dylan,
    how do i make these API’s to produce a VML based graph .I donot want to go with SVG.And also i want the support in mozilla.Can u please help here….

  • This tutorial is excellent, and honestly I’d love to have a few more on the subject. Thanks for the good work !

  • Kiki

    Great tutorial, thanks a lot for that. But I’m missing a possibility to create reverse axis labels (or have I overlooked it?) i.e. having 1 as max value on top of the y axis and 8 as min value.


    makeCharts = function(){

    var chart1 = new dojox.charting.Chart2D(“simplechart”);
    chart1.addPlot(“default”, {type: “Lines”});
    chart1.addAxis(“y”, {vertical: true, min: 8, max: 1});
    chart1.addSeries(“Series 1”, [1, 2, 2, 3, 4, 5, 5, 7]);



    Trying it that way makes the axis lable of the y axis disapear.
    Any idea how to realise that?

  • Kiki

    Btw, tried the code above with FF 3.6.6 and IE8. IE8 makes all axis lables disapear.

  • Tamer Higazi

    The dojo chart engine seems to be very nice. Is there a way after generating the chart, to make a routine for generating the SVG content on the fly?!


  • Adoracion

    I’m using MiamiNice theme in my “pie’s” graphics, but doesn’t provide enough colors, and repeat colors in some sectors, is there any way to define a number of colors?

  • Maur BENTEIN

    The parameter “shadows” does not work. I used “shadow” instead, and it works partially in the sence that the parameter “dw” has no visual effect.

  • Uday

    I cant understand atleast small tags in dojo. So Please find me the easy way to understand dojo well.

  • Mark Crosby

    Your quip “I’ll leave it up to you to explore the parameters for the pie chart” wouldn’t be so annoying if the Dojo documentation was complete or if the pie.js file had some comments and didn’t use obfuscated variable and function names.

    I’ve got too much work to do for my web page using Dojo charting. I don’t have the time to explore, I want some decent documentation! Doesn’t anyone on the Dojo development team want to share that information?

  • shashank

    Hi Doug, great article..
    I have a requirement where i have to show the line graph ( or chart) and i have to show the marker at a particular data point and after that data point the line should be displayed in dotted line.
    Do you have any suggestions to accomplish this.

  • Fickle Vivek

    Documentation for arguments taken by various Chart methods is not proper. Any help is gladly appreciated