Documentation for gRaphael: g.line.js

Update: I found another library that is superior to gRaphael. It’s called Ico by Alex Young. You can find it here: It doesn’t support all of the graph types, but the options more thorough.

gRaphael provides an easy way of creating charts through JavaScript. Unfortunately, many people have complained about how poorly it is documented. In the interest of seeing more good looking charts on websites, I decided to go through the code and post documentation here. This first post is on the line chart library, but I will be posting more on the rest of the library in the future.

To start using the line chart, we need to include the Raphael and the line chart library:

<script src="/script/raphael.js" type="text/javascript" charset="utf-8"></script>
<script src="/script/g.raphael.js" type="text/javascript" charset="utf-8"></script>
<script src="/script/g.line.js" type="text/javascript" charset="utf-8"></script>

Then initialize the chart by passing in the options to the constructor:

var r = Raphael("element");
r.g.linechart(x_offset, y_offset, width, height, x_values_array, y_values_array, options);

x_values_array is either an array of x values, or an array of multiple arrays of x values.
y_values_array is the same as above, but for the y-axis.
If only one array of x values is specified, multiple y value arrays will share these values. If both are specified, each plot will be completely independent of each other.

options is an object with the following possible elements:

var options = {
  gutter: 10,
  symbol: "",
  colors: Raphael.fn.g.colors,
  nostroke: false,
  smooth: false;
  shade: false,
  dash: "",
  axis: "",
  axisxstep: 1,
  axisystep: 1

options.gutter is the default spacing between the edge of the chart area and the graph itself.

options.symbol is either a single symbol or an array of multiple symbols for each line. Just leaving it as a blank (“”) means that it will be a line graph without any decoration at the points. The list of allowable options is:

"" - no symbol
"o" - "disc"
"f" - "flower"
"d" - "diamond"
"s" - "square"
"t" - "triangle"
"*" - "star"
"x" - "cross"
"+" - "plus"
"->"; - "arrow"

options.colors must be an array, even if there is only one line.

options.nostroke controls the line drawing. Set to false (default), it will draw the line. If this is set to true and a symbol is chosen, a scatter type plot can be made.

options.smooth turns on smoothing. No jagged angles will be seen, just smooth curves.

options.shade controls shading the area below the line. No shading happens by default. Set this to true to create an area chart.

options.dash sets the ‘stroke-dasharray’ property on the line element. According to the SVG spec:

‘stroke-dasharray’ controls the pattern of dashes and gaps used to stroke paths. Contains a list of comma and/or white space separated integers that specify the lengths of alternating dashes and gaps. If an odd number of values is provided, then the list of values is repeated to yield an even number of values. Thus, stroke-dasharray: 5,3,2 is equivalent to stroke-dasharray: 5,3,2,5,3,2.

options.axis is a comma or space separated list of axes to show. Seems like it follows the order of css lists: top, right, bottom, left.

option.axisxstep determines how far apart the ticks and axis numbers are placed.

option.axisystep is the same as above, but for the y-axis.

Unfortunately, this is as far as the axis customization goes. I’ve been looking at the parent object and it looks like it wouldn’t be hard to customize the axes further. I’ll post more on this as I figure it out. If anyone wants to look at the g.axis() function and figure out how to add labels and customize the labels on the axis, please let me know what you find.

r.g.linechart() returns a chart object:

chart = {lines, shades, symbols, axis, columns, dots};

That chart object has the following default functions. All of these are overridable.

chart.hoverColumn = function (fin, fout) {
  !columns && createColumns();
  return this;

chart.clickColumn = function (f) {
  !columns && createColumns();;
  return this;

chart.hrefColumn = function (cols) {
  var hrefs =[0], "array") ? arguments[0] : arguments;
  if (!(arguments.length - 1) && typeof cols == "object") {
    for (var x in cols) {
      for (var i = 0, ii = columns.length; i < ii; i++) if (columns[i].axis == x) {
        columns[i].attr("href", cols[x]);
  !columns && createColumns();
  for (i = 0, ii = hrefs.length; i < ii; i++) {
    columns[i] && columns[i].attr("href", hrefs[i]);
  return this;

chart.hover = function (fin, fout) {
  !dots && createDots();
  return this;
}; = function (f) {
  !dots && createDots();;
  return this;

chart.each = function (f) {
  return this;

chart.eachColumn = function (f) {
  return this;

15 thoughts on “Documentation for gRaphael: g.line.js

  1. Thanks a lot. I like Raphael, but yes, the documentation is horrible… actually, non-existent might be a better word.

    Ico is an extension of Raphael and certainly appears easier to use. Thanks for surfacing this option as well as in-depth info the line chart configuration!

  2. Hey, Thanks for posting this, even just knowing the argument names has really helped me get along.

    For such a great library it’s a shame it’s so poorly documented.

  3. Thanks for this much-needed post!

    btw, is Alex Young’s ico an extension of Raphael as stated above? It doesn’t seem to work with IE8, and the fact that Raphael and gRaphael work with IE6-8 is their main selling point for me.

    1. ICO uses Raphaël to draw. It was originally written with the first version of Raphaël. Raphaël was completely rewritten in version 2.0. ICO was tested (not sure of how thoroughly) with Raphaël 2.0 to make sure it still works. If you’re experiencing problems, send Alex Young a bug request at the Github page linked to above.

  4. Thanks for the documentation, but I can’t get the symbol option to work. The only thing that works is if use circle, I’ve tried using an array and a blank value but I get this:
    paper[, “array”) ? sym[j] : sym] is not a function @ js/g.line.js:154

    The updating of gRaphael seems to be really slow, I’ve come across another bug with createColumns() which has already been reported and a fix is available, but it hasn’t been applied in the version distributed yet.:/.

  5. I know this if off topic but I’m looking into starting my own weblog and was curious what all is required to get setup? I’m assuming having a
    blog like yours would cost a pretty penny? I’m not very web savvy so I’m not 100% positive. Any recommendations or advice would be greatly appreciated. Many thanks Check out my website to get more info about forex, if you like.

Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s