Raphaël: cross-browser drawings

Raphaël is an abstraction for web-based vector graphics, which lets you draw shapes and build drawings in a browser via JavaScript code; it's an abstraction that works cross-browser back to Firefox 3 and Internet Explorer 6. The logo itself was drawn with Raphael, so I took a screenshot of it.

For the rest of the article, I will refer to Raphaël as Raphael to avoid confusion, since all the JavaScript code will use the normalized version of the name.

Raphael is a cross-browser adaptation: the jQuery of graphic elements. Vector graphics is based on elements like lines and shapes instead of on raster images like bitmaps. The back ends used by Raphael are HTML 5 SVG in browser with support, and VML for Internet Explorer variations.

Raphael has the most permissive open source license, the MIT license. You can do whatever you want with the code, which is developed by Sencha of Ext JS fame.

A quick example

Here's an example from the docs that I've run in a minute: a canvas where to draw is created, and a circle with a red filling is created.

<script type="text/javascript" src="raphael.js"></script>
<script type="text/javascript">
window.onload = function () {
    // a canvas of 320 × 200 at 10, 50
    paper = Raphael(10, 50, 320, 200);
    // Creates circle at x = 50, y = 40, with radius 10
    circle = paper.circle(50, 40, 10);
    // Sets the fill attribute of the circle to red (#f00)
    circle.attr("fill", "#f00");
}
</script>

The generated DOM (extracted and reformatted for your convenience) in Firefox 5 is:

<svg style="position: absolute; left: 10px; top: 50px;" height="200" width="320" version="1.1" xmlns="http://www.w3.org/2000/svg">
    <desc>Created with Raphaël</desc>
    <defs></defs>
    <circle stroke="#000" fill="#ff0000" r="10" cy="40" cx="50"></circle>
</svg>

A look at the code

raphael.js, as of version 1.5.2, is a single file weighing 60 Kb in the minified version, and with no external dependencies other than a compatible browser (which is really anything you would want to work with.) The uncompressed version for development is functionally equivalent but weighs 150 Kb, with very few comments but lots of links to web pages explaining the hacks used to hide browser differences or gain speed.

In any case, Raphael is defined as an object inside a closure to avoid pollution of the global scope (as you would expect), along with the prototypes of the paper and element objects. Functions are defined anonymously inside and kept on the Raphael object.

The Raphael global variable is the only exposed Api. In case you want to delete the presence of this variable to avoid conflicts, the manual reports you can by calling the ninja() method:

(function (local_raphael) {
    var paper = local_raphael(10, 10, 320, 200);
    …
})(Raphael.ninja());

And that's a reference, of course.

Features

Raphael supports many different features:

• various shapes: circle, rectangle, and ellipse.
• Image and text insertion.
• Higher-level objects typical of vector graphics such as sets of graphic elements and drawing paths.
• Operations on elements such as rotation, translation, scaling and animations.

Extensibility

By intervention on the fields of the Raphael global variable, you can extend the functionalities of the library a bit.

• You can add methods to the canvas via configuration: add them to the Raphael.fn object which is the template.
• You can add methods to the created elements: add them previously to the Raphael.el object.
• You can add event handlers to the DOM elements created by Raphael: if elem is the name of a graphical element created via a method on Raphael, elem.node is its DOMElement.

There is also a charting plugin, gRaphael, implementing commodities such as pie, dot, line or bar charts.

Further resources

Raphael has been around for some time and has encounter the favors of many web developers. There are further tutorials that you can use over the documentation if you want to dive into web-based graphics.

Introduction to the Api with examples for the various functionalities
Chart-specific tutorial

There are also some nice demos provided by the official website itself. Demos are handy to checkout if the library can actually do what you need, but also for cutting out code for experimentation.

Different charts are drawn
Animation and superposition of circles
Australia map with descriptions changing on mouse over
Continuous rotating animation with configuration parameters
Colorized bar charts of different types
Animation of a circle bouncing and moving around, with configurable movements