3 Cross-browser vector graphics the easy way.
7 Raphaël is a small JavaScript library that should simplify your work with vector graphics on the web. If you want to create your own specific chart or image crop and rotate widget, for example, you can achieve it simply and easily with this library.
9 Raphaël uses the [SVG W3C Recommendation](http://www.w3.org/TR/SVG/) and [VML](http://msdn.microsoft.com/en-us/library/bb264280.aspx) (a mostly equivalent implementation for Internet Explorer) as a base for drawing graphics. This means every graphical object you create is also a DOM object, so you can attach JavaScript event handlers or modify them later. Raphaël’s goal is to provide an adapter that will make drawing vector art cross-browser compatible and easy to do.
11 Raphaël currently supports Firefox 3.0+, Safari 3.0+, Opera 9.5+ and Internet Explorer 6.0+.
15 Download and include `raphael.js` (or, `raphael-packed.js` for a minimized version) into your HTML page. When it's loaded, use it as simply as:
17 // Creates canvas 320 × 200 at 10, 50
18 var paper = Raphael(10, 50, 320, 200);
19 // Creates circle at x = 50, y = 40, with radius 10
20 var circle = paper.circle(50, 40, 10);
21 // Sets the fill attribute of the circle to red (#f00)
22 circle.attr("fill", "#f00");
23 // Sets the stroke attribute of the circle to white (#fff)
24 circle.attr("stroke", "#fff");
28 This section provides a function reference for the Raphaël JavaScript library.
34 Creates a canvas object on which to draw. You must do this first, as all future calls to drawing methods from this instance will be bound to this canvas.
38 1. container HTMLElement or string
51 // Each of the following examples create a canvas that is 320px wide by 200px high
52 // Canvas is created at the viewport's 10,50 coordinate
53 var paper = Raphael(10, 50, 320, 200);
54 // Canvas is created at the top left corner of the #notepad element (or its top right corner in dir="rtl" elements)
55 var paper = Raphael(document.getElementById("notepad"), 320, 200);
57 var paper = Raphael("notepad", 320, 200);
59 ### Element’s generic methods
61 Each object created on the canvas shares these same generic methods:
65 Gives you a reference to the DOM object, so you can assign event handlers or just mess around.
69 var c = paper.circle(10, 10, 10); // draw a circle at coordinate 10,10 with radius of 10
70 c.node.onclick = function () { c.attr("fill", "red"); };
74 Rotates the element by the given degree from either its 0,0 corner or its centre point.
78 1. degree number Degree of rotation (0 – 360°)
79 2. isAbsolute boolean \[optional\] Specifies the rotation point. Use `true` to rotate the element around its center point. The default, `false`, rotates the element from its 0,0 coordinate.
83 var c = paper.circle(10, 10, 10);
84 c.rotate(45); // rotation is relative
85 c.rotate(45, true); // rotation is absolute
89 Moves the element around the canvas by the given distances.
93 1. dx number Pixels of translation by X axis
94 2. dy number Pixels of translation by Y axis
98 var c = paper.circle(10, 10, 10);
99 c.translate(10, 10); // moves the circle down the canvas, in a diagonal line
103 Resizes the element by the given multiplier.
107 1. Xtimes number Amount to scale horizontally
108 2. Ytimes number Amount to scale vertically
112 var c = paper.circle(10, 10, 10);
113 c.scale(1.5, 1.5); // makes the circle 1.5 times larger
114 c.scale(.5, .75); // makes the circle half as wide, and 75% as high
118 Sets the attributes of elements directly.
122 1. attributeName string
129 ###### Possible parameters
131 Please refer to the [SVG specification](http://www.w3.org/TR/SVG/) for an explanation of these parameters.
136 * fill-opacity number
151 * stroke-dasharray string \[“-”, “.”, “-.”, “-..”, “. ”, “- ”, “--”, “- .”, “--.”, “--..”\]
152 * stroke-linecap string \[“butt”, “square”, “round”, “miter”\]
153 * stroke-linejoin string \[“butt”, “square”, “round”, “miter”\]
154 * stroke-miterlimit number
155 * stroke-opacity number
156 * stroke-width number
164 var c = paper.circle(10, 10, 10);
165 c.attr("fill", "black"); // using strings
166 c.attr({fill: "#000", stroke: "#f00", opacity: 0.5}); // using params object
170 Linearly changes an attribute from its current value to its specified value in the given amount of milliseconds.
174 1. newAttrs object A parameters object of the animation results. (Not all attributes can be animated.)
175 2. ms number The duration of the animation, given in milliseconds.
176 3. callback function \[optional\]
178 ##### Attributes that can be animated
180 The `newAttrs` parameter accepts an object whose properties are the attributes to animate. However, not all attributes listed in the `attr` method reference can be animated. The following is a list of those properties that can be animated:
185 * fill-opacity number
196 * stroke-opacity number
197 * stroke-width number
205 var c = paper.circle(10, 10, 10);
206 c.animate({cx: 20, r: 20}, 2000);
210 Returns the dimensions of an element.
214 var c = paper.circle(10, 10, 10);
215 var width = c.getBBox().width;
219 Moves the element so it is the closest to the viewer’s eyes, on top of other elements.
223 var c = paper.circle(10, 10, 10);
228 Moves the element so it is the furthest from the viewer’s eyes, behind other elements.
232 var c = paper.circle(10, 10, 10);
237 Inserts current object before the given one
241 var r = paper.rect(10, 10, 10, 10);
242 var c = paper.circle(10, 10, 10);
247 Inserts current object after the given one
251 var c = paper.circle(10, 10, 10);
252 var r = paper.rect(10, 10, 10, 10);
255 ### Graphic Primitives
263 1. x number X coordinate of the centre
264 2. y number Y coordinate of the centre
269 var c = paper.circle(10, 10, 10);
277 1. x number X coordinate of top left corner
278 2. y number Y coordinate of top left corner
281 5. r number \[optional\] radius for rounded corners, default is 0
286 var c = paper.rect(10, 10, 10, 10);
287 // rectangle with rounded corners
288 var c = paper.rect(10, 10, 100, 50, 10);
296 1. x number X coordinate of the centre
297 2. y number X coordinate of the centre
298 3. rx number Horisontal radius
299 4. ry number Vertical radius
303 var c = paper.ellipse(100, 100, 30, 40);
307 Embeds an image into the SVG/VML canvas.
311 1. src string URI of the source image
312 2. x number X coordinate position
313 3. y number Y coordinate position
314 4. width number Width of the image
315 5. height number Height of the image
319 var c = paper.image("apple.png", 10, 10, 100, 100);
327 1. x number X coordinate position
328 2. y number Y coordinate position
329 3. text string The text string to draw.
333 var t = paper.text(10, 10, "Look mom, I'm scalable!");
337 Initialises path drawing. Typically, this function returns an empty `path` object and to draw paths you use its built-in methods like `lineTo` and `curveTo`. However, you can also specify a path literally by supplying the path data as a second argument.
341 1. params object Attributes for the resulting path as described in the `attr` reference.
342 2. pathString string \[optional\] Path data in [SVG path string format](http://www.w3.org/TR/SVG/paths.html#PathData).
346 var c = paper.path({stroke: "#036"}).moveTo(10, 10).lineTo(50, 50); // draw a diagonal line
347 var c = paper.path({stroke: "#036"}, "M 10 10 L 50 50"); // same
353 Sets a trigger to count all following units as absolute ones, unless said otherwise. (This is on by default.)
357 var c = paper.path({stroke: "#036"}).absolutely()
358 .moveTo(10, 10).lineTo(50, 50);
362 Sets a trigger to count all following units as relative ones, unless said otherwise.
366 var c = paper.path({stroke: "#036"}).relatively()
367 .moveTo(10, 10).lineTo(50, 50);
371 Moves the drawing point to the given coordinates.
375 1. x number X coordinate
376 2. y number Y coordinate
380 // Begins drawing the path at coordinate 10,10
381 var c = paper.path({stroke: "#036"}).moveTo(10, 10).lineTo(50, 50);
385 Draws a straight line to the given coordinates.
389 1. x number X coordinate
390 2. y number Y coordinate
394 // Draws a line starting from 10,10 to 50,50
395 var c = paper.path({stroke: "#036"}).moveTo(10, 10).lineTo(50, 50);
399 Draws a curved line to the given coordinates. The line will have horizontal anchors on start and on finish.
409 var c = paper.path({stroke: "#036"}).moveTo(10, 10).cplineTo(50, 50);
413 Draws a bicubic curve to the given coordinates.
426 var c = paper.path({stroke: "#036"}).moveTo(10, 10).curveTo(10, 15, 45, 45, 50, 50);
430 Draws a quadratic curve to the given coordinates.
441 var c = paper.path({stroke: "#036"}).moveTo(10, 10).curveTo(10, 15, 45, 45, 50, 50);
443 #### addRoundedCorner
445 Draws a quarter of a circle from the current drawing point.
450 2. dir string Two-letter directional instruction, as described below.
465 var c = paper.path({stroke: "#036"}).moveTo(10, 10).addRoundedCorner(10, "rd");
469 Closes the path being drawn.
473 var c = paper.path({stroke: "#036"}).moveTo(10, 10).andClose();
477 [http://www.opensource.org/licenses/mit-license.php](http://www.opensource.org/licenses/mit-license.php)
479 Copyright (c) 2008 Dmitry Baranovskiy ([http://raphaeljs.com](http://raphaeljs.com/))