The Web Developer Toolbox: Raphaël

This is the first of a series of articles dedicated to the useful libraries that all web developers should have in their toolbox. My intent is to show you what those libraries can do and help you to use them at their best. This first article is dedicated to the Raphaël library.


Raphaël is a library originally written by Dmitry Baranovskiy and is now part of Sencha Labs.

The goal of this library is to simplify work with vector graphics on the Web. Raphaël relies on the SVG W3C Recommendation (which is well supported in all modern browsers) and falls back to the Micrsoft VML language in order to address legacy versions of Internet Explorer. It also tries to harmonize some working issues across SVG implementations such as the SVG Animations. As a consequence, Raphaël is a very nice wrapper to produce consistent kick-ass graphics all over the Web.

Basic usage

The library has very good documentation with many examples. Do not hesitate to use it extensively.

The following example will draw a simple red circle inside an HTML element with the id “myPaper”.

// the following example creates a drawing zone
// that is 100px wide by 100px high.
// This drawing zone is created at the top left corner
// of the #myPaper element (or its top right corner in
// dir="rtl" elements)
var paper = Raphael("myPaper", 100, 100);

// The circle will have a radius of 40
// and its center will be at coordinate 50,50
var c =, 50, 40);

// The circle will be filled with red
// Note that the name of each element property
// follow the SVG recommendation
    fill: "#900"

Advanced usage

Despite the fact that Raphaël reduces the possibilities offered by SVG (mainly because of the VML fallback) it allows one to perform very advanced stuff:

  • Advance Matrix transformation
  • Advance event handler
  • Cross browser animations
  • Easy drag system
  • Path intersection detection

Raphaël is also extensible through an extension system that allows you to build custom functions.

For example, here’s an extension to draw pie charts:

 * Pie method
 * cx: x position of the rotating center of the pie
 * cy: y position of the rotating center of the pie
 * r : radius of the pie
 * a1: angle expressed in degrees where the pie start
 * a2: angle expressed in degrees where the pie end
Raphael.fn.pie = function (cx, cy, r, a1, a2) {
    var d,
        flag = (a2 - a1) > 180;

    a1 = (a1 % 360) * Math.PI / 180;
    a2 = (a2 % 360) * Math.PI / 180;

    d = [
        // Setting the rotating axe of the pie
        "M", cx, cy,

        // Go to the start of the curve
        "l", r * Math.cos(a1), r * Math.sin(a1),

        // Drawing the curve to its end
        "A", r, r, "0", +flag, "1",
        cx + r * Math.cos(a2), cy + r * Math.sin(a2),

        // Closing the path

    return this.path(d.join(' '));

Note: In the example above, you have to be familiar with the SVG path syntax (Raphaël will convert it to the VML syntax under the hood), but once it’s done you can reuse it as any other Raphaël primitive. Look at this extension working to draw a color wheel on jsFiddle.

JSFiddle demo.

Limits and precaution

If you are not familiar with SVG and/or want to support legacy MS Internet Explorer browsers, this tool is made for you. However, it’s a JavaScript library, which means that you have to know JavaScript to use it. You cannot use SVG and ask Raphaël to parse it and interpret it (to do that, it exists other libraries).

In terms of browser support, Raphaël gives you a large base. Raphaël currently supports Firefox 3.0+, Safari 3.0+, Chrome 5.0+, Opera 9.5+ and Internet Explorer 6.0+.

In fact, the only browser that can not take advantage of Raphaël is the native browser for Android 1.x and 2.x (and obviously many feature phone browsers). This is due to the fact that those browsers do not support any vector language. Android starts (partially) supporting SVG with Android 3.0 so take care if you want to work with all mobile devices.


Raphaël was the first library to allow web designers and web developers to use SVG in the wild. If you want to write some nice applications without the need of the full SVG DOM API or if you have to support legacy browsers, this library will give you some power.

In conclusion, here are some cool usages of Raphaël:

About Jeremie Patonnier

Jeremie is a long time contributor/employee to the Mozilla Developer Network, and a professional web developer since 2000. He's advocating web standards, writing documentation and creating all sort of content about web technologies with the will to make them accessible to everybody.

More articles by Jeremie Patonnier…


  1. pd

    This series of articles sounds promising, thanks.

    Although SVG still seems more of a solution waiting for a problem, vector graphics support in HTML is of course critical. It’s kinda weird though in the Flash’s use of vectors for tweening objects on a ‘stage’ and so forth almost seems like a bygone era now, perhaps akin to irrtating vanity gifs and early DHTML gawdiness. Here’s hoping libraries like this will be used in more appropriate ways ::)

    One such use would be for animated bar graphs I hope. With HTML5 theoretically capable of surpassing Powerpoint for presentations, it’s ability to do show/hide of slides and bullets points, along with swanky looking animated graphs is important.

    May 15th, 2012 at 07:57

    1. Jeremie Patonnier


      Thanks to HTML5, SGV has strong advantages in modern web design. One of the biggest use case is about responsive web design. Having images able to scale without loosing quality is a big hit to build interface working on low resolution screen as well as on high resolution screen (such as on iPad3 or iPhone4).

      Another point is that some of the technologies currently available with SVG are in the process to be extended to HTML through CSS (filters, transforms, etc.). In many cases SVG offer a reliable fallback for all those uprising CSS technics.

      May 15th, 2012 at 08:54

  2. zoomclub

    Have you seen D3? Should check it out to see some great SVG/HTML work. See the following link to discover more :

    May 16th, 2012 at 23:52

    1. Jeremie Patonnier

      Yes, absolutely :)

      There is plan to have a full article about D3 in the near future ;)

      May 17th, 2012 at 00:15

Comments are closed for this article.