Over the last few years I have heard more and more good things about the javascript library Raphaël. A project I was working on recently afforded me the opportunity to experiment with it fully. I discovered that it is really powerful and actually fun and easy to work with. In fact, it feels like it replaces a lot of the functionality you could create in Flash, when that was the standard for robust, dynamic interfaces. But unlike Flash, mobile browsers are starting to support SVG across the board (from a few years ago) and Raphaël will convert the SVG code to VML for IE8 and below.

In this tutorial I walk through some basic examples of using Raphaël and then include code for a more complex example where I create a custom pie graph. This tutorial assumes that you have a basic knowledge in JavaScript code and that you are familiar with using jQuery. But before I get into the tutorial, let’s go through the basics.

What is Raphaël?

Raphaël is a JavaScript library that allows for creating SVG’s on the web. For browsers that do not support SVG, it will automatically convert the code to VML (IE8 and below).

What makes Raphaël awesome is how it fits very well with responsive design. Since it creats vector graphics, it can scale without losing clarity or stretching out pixels, like you find in raster graphics.

Getting Started

The first thing you will want to do is download the raphael.js file. I recommend using jQuery to help work with the dom, but jQuery is not required to use Raphaël. You will also want to bookmark the documentation page, as that will be useful in accessing different functionality and options for the library. I also recommend going through the examples they have on their site to get a feeling for what you can do with the library. In fact, if you can find an example that sends you in the right direction in what you are trying to do, I recommend starting from there.

When using Raphaël, you will always need to create a canvas to draw on. This defines the total area we have to work with. You will be referencing this object when you draw lines and shapes, so make sure you call this before those samples. With the Raphael() call, we are sending the id of the <div> where we want to draw the canvas.

Below is the basic html structure for a page that uses Raphaël, including creating the canvas, that I’m using with these examples. Note that the CSS here is very important, as we are using it to define the size of the canvas.

Drawing Lines

A key concept when using Raphaël is understanding how lines are drawn. There are different ways you can do this, and you will want to understand the different options. For the examples in this section, we will simply use Paper.path().

Keep in mind that all of the commands we are sending to this method are SVG commands. So as another option, you could use several software programs to generate these commands. You can reference the W3 SVG standards if you want a more in depth and technical description in what you can do.

Here is a sample command that draws a line. Underneath the code, I explain what each part of the command is doing.

M: This tells the system where to move the cursor. It then is followed by a 0 and 240, which are x,y coordinates. In human terms it is saying “From the top left corner of the canvas, move the cursor 0 pixels to the right and 240 pixels down”.

l: This is a lowercase “L” and specifies that we want to draw a line, relative to where the cursor is at. An uppercase “L” uses an absolute position from the top left corner of the canvas. With the code above, the command is saying “From where the cursor is at, draw a line 640 pixels to the right and 0 pixels down.”

With both of these commands you can use negative numbers. For the x coordinate, this would make it go to the left and for the y coordinate, this would tell it to go up.

Here are a few additional examples:

You can combine all of these into one path value. The only reason you might want to separate them is if you wanted to apply different styling or effects to each line. But in most cases in dealing with lines, you will want to combine them into one path, like this:

See the code in action.

Just like the “L” call, you can make the “M” call lower case. This makes the cursor move relative to where it is at currently. So we could draw a triangle in the center of a rectangle with this command:

See the code in action.

Drawing Shapes and Text

You could create shapes and text manually using the path() method. But there are much simpler ways for drawing basic shapes and text using the library. A few examples are circle(), rect() and text(). See an example that draws all of them on the same canvas below.

See the code in action.

Attributes

At this point we haven’t customized the look of the objects we have been drawing. What if you want to change the fill color of the object? Or the border? Or the cursor when the mouse goes over the object? For customizing the look of any object you draw in Raphaël, you will want to use Element.attr().

Here is some code that creates a circle and changes the fill color.

Or you could make the code look like this to accomplish the same thing.

You can change as many properties of the object as you want.

Once you have drawn an object, you can also add click, mouseover or any other jQuery events onto that object very easily. Take a look at this code to see a modified example that changes the attributes of the object and also modifies one of the objects when the text is clicked. From here you see the benefits in using jQuery with Raphaël.

Custom Pie Graph

Recently we created a custom pie graph directly in SVG. But the problem was that the SVG would not load in IE8. To get this working in IE8, we decided to redo this using Raphaël.

When tackling a complex customization like this, you will want to break the task into simpler steps that you implement one at a time. I first got a basic pie graph to display. I then implemented the different colors for each slice of the pie. Next I modified how far each slice goes out, depending on the value. Finally I created each section slice (to make each section clickable).

If you take a look at the code, you will notice that I am getting the values of each slice from a hidden html table on the page. This opens up the possibility in how to get your data into something like a graph.

See the code in action.

Once you get over the initial learning curve using Raphaël, you begin to realize the potential this library has to create some really cool, dynamic interfaces. And when combined with jQuery, implementing this becomes even easier!