Creates a copy of existing animation object with given delay.
Parameters
Returns: object new altered Animation object
Creates a copy of existing animation object with given repetition.
Parameters
InfinityReturns: object new altered Animation object
Creates and starts animation for given element.
Parameters
cubic‐bezier(XX, XX, XX, XX)or
Returns: object original element
Acts similar to Element.animate, but ensure that given animation runs in sync with another given element.
Parameters
cubic‐bezier(XX, XX, XX, XX)or
Returns: object original element
Sets the attributes of the element.
Parameters
or
or
or
Returns: object Element if attrsName & value or params are passed in.
Returns: ... value of the attribute if only attrsName is passed in.
Returns: array array of values of the attribute if attrsNames is passed in.
Returns: object object of attributes if nothing is passed in.
Possible parameters
Please refer to the SVG specification for an explanation of these parameters.
<type>[-<width>[-<length>]]. Possible types: classic, block, open, oval, diamond, none, width: wide, narrow, midium, length: long, short, midium.
-”, “.”, “-.”, “-..”, “. ”, “- ”, “--”, “- .”, “--.”, “--..”]
butt”, “square”, “round”]
bevel”, “round”, “miter”]
\n for multiline text
start”, “middle”, “end”], default is “middle”
Gradients
Linear gradient format: “‹angle›-‹colour›[-‹colour›[:‹offset›]]*-‹colour›”, example: “90-#fff-#000” – 90°
gradient from white to black or “0-#fff-#f00:20-#000” – 0° gradient from white via red (at 20%) to black.
radial gradient: “r[(‹fx›, ‹fy›)]‹colour›[-‹colour›[:‹offset›]]*-‹colour›”, example: “r#fff-#000” –
gradient from white to black or “r(0.25, 0.75)#fff-#000” – gradient from white to black with focus point
at 0.25, 0.75. Focus point coordinates are in 0..1 range. Radial gradients can only be applied to circles and ellipses.
Path String
Please refer to SVG documentation regarding path string. Raphaël fully supports it.
Colour Parsing
red”, “green”, “cornflowerblue”, etc)#000”, “#fc0”, etc)#000000”, “#bd2300”)rgb(200, 100, 0)”)rgb(100%, 175%, 0%)”)rgba(200, 100, 0, .5)”)rgba(100%, 175%, 0%, 50%)”)hsb(0.5, 0.25, 1)”)hsl(240deg, 1, .5)” or, if you want to go fancy, “hsl(240°, 1, .5)”Adds event handler for click for the element.
Parameters
Returns: object Element
Returns: object clone of a given element
Adds or retrieves given value asociated with given key. See also Element.removeData
Parameters
Returns: object Element
or, if value is not specified:
Returns: any value
Usage
for (var i = 0, i < 5, i++) {
paper.circle(10 + 15 * i, 10, 10)
.attr({fill: "#000"})
.data("i", i)
.click(function () {
alert(this.data("i"));
});
}
Adds event handler for double click for the element.
Parameters
Returns: object Element
Adds event handlers for drag of the element.
Parameters
Additionaly following drag events will be triggered: drag.start.<id> on start,
drag.end.<id> on end and drag.move.<id> on every move. When element will be dragged over another element
drag.over.<id> will be fired as well.
Start event and start handler will be called in specified context or in context of the element with following parameters:
Move event and move handler will be called in specified context or in context of the element with following parameters:
End event and end handler will be called in specified context or in context of the element with following parameters:
Returns: object Element
Return bounding box for a given element
Parameters
true if you want to have bounding box before transformations. Default is false.Returns: object Bounding box object:
Return coordinates of the point located at the given length on the given path. Only works for element of “path” type.
Parameters
Returns: object representation of the point:
Return subpath of a given element from given length to given length. Only works for element of “path” type.
Parameters
Returns: string pathstring for the segment
Returns length of the path in pixels. Only works for element of “path” type.
Returns: number length.
Return set of elements that create glow-like effect around given element. See Paper.set.
Note: Glow is not connected to the element. If you change element attributes it won’t adjust itself.
Parameters
10
false
0.5
0
0
black
Returns: object Paper.set of elements that represents glow
Makes element invisible. See Element.show.
Returns: object Element
Adds event handlers for hover for the element.
Parameters
Returns: object Element
Unique id of the element. Especially usesful when you want to listen to events of the element,
because all events are fired in format <module>.<action>.<id>. Also useful for Paper.getById method.
Inserts current object after the given one.
Returns: object Element
Inserts current object before the given one.
Returns: object Element
Adds event handler for mousedown for the element.
Parameters
Returns: object Element
Adds event handler for mousemove for the element.
Parameters
Returns: object Element
Adds event handler for mouseout for the element.
Parameters
Returns: object Element
Adds event handler for mouseover for the element.
Parameters
Returns: object Element
Adds event handler for mouseup for the element.
Parameters
Returns: object Element
Reference to the next element in the hierarchy.
Gives you a reference to the DOM object, so you can assign event handlers or just mess around. Note: Don’t mess with it.
Usage
// draw a circle at coordinate 10,10 with radius of 10
var c = paper.circle(10, 10, 10);
c.node.onclick = function () {
c.attr("fill", "red");
};
Shortcut for assigning event handler for drag.over.<id> event, where id is id of the element (see Element.id).
Parameters
Internal reference to “paper” where object drawn. Mainly for use in plugins and element extensions.
Usage
Raphael.el.cross = function () {
this.attr({fill: "red"});
this.paper.path("M10,10L50,50M50,10L10,50")
.attr({stroke: "red"});
}
Stops animation of the element with ability to resume it later on.
Parameters
Returns: object original element
Reference to the previous element in the hierarchy.
Internal reference to Raphael object. In case it is not available.
Usage
Raphael.el.red = function () {
var hsb = this.paper.raphael.rgb2hsb(this.attr("fill"));
hsb.h = 1;
this.attr({fill: this.paper.raphael.hsb2rgb(hsb).hex});
}
Removes element from the paper.
Removes value associated with an element by given key. If key is not provided, removes all the data of the element.
Parameters
Returns: object Element
Resumes animation if it was paused with Element.pause method.
Parameters
Returns: object original element
Adds rotation by given angle around given point to the list of transformations of the element.
Parameters
If cx & cy aren’t specified centre of the shape is used as a point of rotation.
Returns: object Element
Adds scale by given amount relative to given point to the list of transformations of the element.
Parameters
If cx & cy aren’t specified centre of the shape is used instead.
Returns: object Element
Sets the status of animation of the element in milliseconds. Similar to Element.status method.
Parameters
Returns: object original element if value is specified
Note, that during animation following events are triggered:
On each animation frame event anim.frame.<id>, on start anim.start.<id> and on end anim.finish.<id>.
Makes element visible. See Element.hide.
Returns: object Element
Gets or sets the status of animation of the element.
Parameters
Returns: number status
or
Returns: array status if anim is not specified. Array of objects in format:
or
Returns: object original element if value is specified
Stops animation of the element.
Parameters
Returns: object original element
Moves the element so it is the furthest from the viewer’s eyes, behind other elements.
Returns: object Element
Moves the element so it is the closest to the viewer’s eyes, on top of other elements.
Returns: object Element
Adds event handler for touchcancel for the element.
Parameters
Returns: object Element
Adds event handler for touchend for the element.
Parameters
Returns: object Element
Adds event handler for touchmove for the element.
Parameters
Returns: object Element
Adds event handler for touchstart for the element.
Parameters
Returns: object Element
Adds transformation to the element which is separate to other attributes,
i.e. translation doesn’t change x or y of the rectange. The format
of transformation string is similar to the path string syntax:
"t100,100r30,100,100s2,2,100,100r45s1.5"
Each letter is a command. There are four commands: t is for translate, r is for rotate, s is for
scale and m is for matrix.
So, the example line above could be read like “translate by 100, 100; rotate 30° around 100, 100; scale twice around 100, 100; rotate 45° around centre; scale 1.5 times relative to centre”. As you can see rotate and scale commands have origin coordinates as optional parameters, the default is the centre point of the element. Matrix accepts six parameters.
Usage
var el = paper.rect(10, 20, 300, 200);
// translate 100, 100, rotate 45°, translate -100, 0
el.transform("t100,100r45t-100,0");
// if you want you can append or prepend transformations
el.transform("...t50,50");
el.transform("s2...");
// or even wrap
el.transform("t50,50...t-50-50");
// to reset transformation call method with empty string
el.transform("");
// to get current value call it without parameters
console.log(el.transform());
Parameters
If tstr isn’t specified
Returns: string current transformation string
else
Returns: object Element
Adds translation by given amount to the list of transformations of the element.
Parameters
Returns: object Element
Removes event handler for click for the element.
Parameters
Returns: object Element
Removes event handler for double click for the element.
Parameters
Returns: object Element
Removes all drag event handlers from given element.
Removes event handlers for hover for the element.
Parameters
Returns: object Element
Removes event handler for mousedown for the element.
Parameters
Returns: object Element
Removes event handler for mousemove for the element.
Parameters
Returns: object Element
Removes event handler for mouseout for the element.
Parameters
Returns: object Element
Removes event handler for mouseover for the element.
Parameters
Returns: object Element
Removes event handler for mouseup for the element.
Parameters
Returns: object Element
Removes event handler for touchcancel for the element.
Parameters
Returns: object Element
Removes event handler for touchend for the element.
Parameters
Returns: object Element
Removes event handler for touchmove for the element.
Parameters
Returns: object Element
Removes event handler for touchstart for the element.
Parameters
Returns: object Element
Adds given matrix to existing one.
Parameters
Returns copy of the matrix
Returns: object Matrix
Returns inverted version of the matrix
Returns: object Matrix
Rotates the matrix
Parameters
Scales the matrix
Parameters
Splits matrix into primitive transformations
Returns: object in format:
Return transform string that represents given matrix
Returns: string transform string
Translate the matrix
Parameters
Return x coordinate for given point after transformation described by the matrix. See also Matrix.y
Parameters
Returns: number x
Return y coordinate for given point after transformation described by the matrix. See also Matrix.x
Parameters
Returns: number y
Points to the bottom element on the paper
Draws a circle.
Parameters
Returns: object Raphaël element object with type “circle”
Usage
var c = paper.circle(50, 50, 40);
Clears the paper, i.e. removes all the elements.
If you have a set of attributes that you would like to represent as a function of some number you can do it easily with custom attributes:
Usage
paper.customAttributes.hue = function (num) {
num = num % 1;
return {fill: "hsb(" + num + ", .75, 1)"};
};
// Custom attribute “hue” will change fill
// to be given hue with fixed saturation and brightness.
// Now you can use it like this:
var c = paper.circle(10, 10, 10).attr({hue: .45});
// or even like this:
c.animate({hue: 1}, 1e3);
// You could also create custom attribute
// with multiple parameters:
paper.customAttributes.hsb = function (h, s, b) {
return {fill: "hsb(" + [h, s, b].join(",") + ")"};
};
c.attr({hsb: ".5 .8 1"});
c.animate({hsb: "1 0 .5"}, 1e3);
Draws an ellipse.
Parameters
Returns: object Raphaël element object with type “ellipse”
Usage
var c = paper.ellipse(50, 50, 40, 20);
Executes given function for each element on the paper
If callback function returns false it will stop loop running.
Parameters
Returns: object Paper object
Returns you element by its internal ID.
Parameters
Returns: object Raphaël element object
Returns you topmost element under given point.
Returns: object Raphaël element object
Parameters
Usage
paper.getElementByPoint(mouseX, mouseY).attr({stroke: "#f00"});
Finds font object in the registered fonts by given parameters. You could specify only one word from the font name, like “Myriad” for “Myriad Pro”.
Parameters
Returns: object the font object
Usage
paper.print(100, 100, "Test string", paper.getFont("Times", 800), 30);
Embeds an image into the surface.
Parameters
Returns: object Raphaël element object with type “image”
Usage
var c = paper.image("apple.png", 10, 10, 80, 80);
Creates a path element by given path data string.
Parameters
Path string consists of one-letter commands, followed by comma seprarated arguments in numercal form. Example:
"M10,20L30,40"
Here we can see two commands: “M”, with arguments (10, 20) and “L” with arguments (30, 40). Upper case letter mean command is absolute, lower case—relative.
Here is short list of commands available, for more details see SVG path string format.
| Command | Name | Parameters |
|---|---|---|
| M | moveto | (x y)+ |
| Z | closepath | (none) |
| L | lineto | (x y)+ |
| H | horizontal lineto | x+ |
| V | vertical lineto | y+ |
| C | curveto | (x1 y1 x2 y2 x y)+ |
| S | smooth curveto | (x2 y2 x y)+ |
| Q | quadratic Bézier curveto | (x1 y1 x y)+ |
| T | smooth quadratic Bézier curveto | (x y)+ |
| A | elliptical arc | (rx ry x-axis-rotation large-arc-flag sweep-flag x y)+ |
| R | Catmull-Rom curveto* | x1 y1 (x y)+ |
* “Catmull-Rom curveto” is a not standard SVG command and added in 2.0 to make life easier.
Usage
var c = paper.path("M10 10L90 90");
// draw a diagonal line:
// move to 10,10, line to 90,90
Creates set of shapes to represent given font at given position with given size. Result of the method is set object (see Paper.set) which contains each letter as separate path object.
Parameters
16"baseline" or "middle", default is "middle"-1..1, default is 0Returns: object resulting set of letters
Usage
var txt = r.print(10, 50, "print", r.getFont("Museo"), 30).attr({fill: "#fff"});
// following line will paint first letter in red
txt[0].attr({fill: "#f00"});
Points to the Raphael object/function
Draws a rectangle.
Parameters
Returns: object Raphaël element object with type “rect”
Usage
// regular rectangle
var c = paper.rect(10, 10, 50, 50);
// rectangle with rounded corners
var c = paper.rect(40, 40, 50, 50, 10);
Removes the paper from the DOM.
Fixes the issue of Firefox and IE9 regarding subpixel rendering. If paper is dependant on other elements after reflow it could shift half pixel which cause for lines to lost their crispness. This method fixes the issue.
There is an inconvenient rendering bug in Safari (WebKit): sometimes the rendering should be forced. This method should help with dealing with this bug.
Creates array-like object to keep and operate several elements at once. Warning: it doesn’t create any elements for itself in the page, it just groups existing elements. Sets act as pseudo elements — all methods available to an element can be used on a set.
Returns: object array-like object that represents set of elements
Usage
var st = paper.set();
st.push(
paper.circle(10, 10, 5),
paper.circle(30, 10, 5)
);
st.attr({fill: "red"}); // changes the fill of both circles
See Paper.setStart. This method finishes catching and returns resulting set.
Returns: object set
If you need to change dimensions of the canvas call this method
Parameters
Usage
var st = paper.set();
st.push(
paper.circle(10, 10, 5),
paper.circle(30, 10, 5)
);
st.attr({fill: "red"});
Creates Paper.set. All elements that will be created after calling this method and before calling Paper.setFinish will be added to the set.
Usage
paper.setStart();
paper.circle(10, 10, 5),
paper.circle(30, 10, 5)
var st = paper.setFinish();
st.attr({fill: "red"}); // changes the fill of both circles
Sets the view box of the paper. Practically it gives you ability to zoom and pan whole paper surface by specifying new boundaries.
Parameters
00true if you want graphics to fit into new boundary boxDraws a text string. If you need line breaks, put “\n” in the string.
Parameters
Returns: object Raphaël element object with type “text”
Usage
var t = paper.text(50, 50, "Raphaël\nkicks\nbutt!");
Points to the topmost element on the paper
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.
Parameters
or
or
or
undefined.Returns: object Paper
Usage
// Each of the following examples create a canvas
// that is 320px wide by 200px high.
// Canvas is created at the viewport’s 10,50 coordinate.
var paper = Raphael(10, 50, 320, 200);
// Canvas is created at the top left corner of the #notepad element
// (or its top right corner in dir="rtl" elements)
var paper = Raphael(document.getElementById("notepad"), 320, 200);
// Same as above
var paper = Raphael("notepad", 320, 200);
// Image dump
var set = Raphael(["notepad", 320, 200, {
type: "rect",
x: 10,
y: 10,
width: 25,
height: 25,
stroke: "#f00"
}, {
type: "text",
x: 30,
y: 40,
text: "Dump"
}]);
Returns angle between two or three points
Parameters
Returns: number angle in degrees.
Creates an animation object that can be passed to the Element.animate or Element.animateWith methods. See also Animation.delay and Animation.repeat methods.
Parameters
cubic‐bezier(XX, XX, XX, XX)Returns: object Animation
Parses the color string and returns object with all values for the given color.
Parameters
Returns: object Combined RGB & HSB object in format:
true if string can’t be parsed,
Transform angle to degrees
Parameters
Returns: number angle in degrees.
Object that contains easing formulas for animation. You could extend it with your own. By default it has following list of easing:
See also Easing demo.
You can add your own method to elements. This is usefull when you want to hack default functionality or want to wrap some common transformation or attributes in one method. In difference to canvas methods, you can redefine element method at any time. Expending element methods wouldn’t affect set.
Usage
Raphael.el.red = function () {
this.attr({fill: "#f00"});
};
// then use it
paper.circle(100, 100, 20).red();
Utility method Find dot coordinates on the given cubic bezier curve at the given t.
Parameters
Returns: object point information in format:
You can add your own method to the canvas. For example if you want to draw a pie chart,
you can create your own pie chart function and ship it as a Raphaël plugin. To do this
you need to extend the Raphael.fn object. Please note that you can create your own namespaces
inside the fn object — methods will be run in the context of canvas anyway. You should alter
the fn object before a Raphaël instance is created, otherwise it will take no effect.
Usage
Raphael.fn.arrow = function (x1, y1, x2, y2, size) {
return this.path( ... );
};
// or create namespace
Raphael.fn.mystuff = {
arrow: function () {…},
star: function () {…},
// etc…
};
var paper = Raphael(10, 10, 630, 480);
// then use it
paper.arrow(10, 10, 30, 30, 5).attr({fill: "#f00"});
paper.mystuff.arrow();
paper.mystuff.star();
Simple format function. Replaces construction of type “{<number>}” to the corresponding argument.
Parameters
Returns: string formated string
Usage
var x = 10,
y = 20,
width = 40,
height = 50;
// this will draw a rectangular shape equivalent to "M10,20h40v50h-40z"
paper.path(Raphael.format("M{1},{2}h{3}v{4}h{5}z", x, y, width, height, -width));
A little bit more advanced format function than Raphael.format. Replaces construction of type “{<name>}” to the corresponding argument.
Parameters
Returns: string formated string
Usage
// this will draw a rectangular shape equivalent to "M10,20h40v50h-40z"
paper.path(Raphael.format("M{x},{y}h{dim.width}v{dim.height}h{dim['negative width']}z", {
x: 10,
y: 20,
dim: {
width: 40,
height: 50,
"negative width": -40
}
}));
On each call returns next colour in the spectrum. To reset it back to red call Raphael.getColor.reset
Parameters
0.75Returns: string hex representation of the colour.
Resets spectrum position for Raphael.getColor back to red.
Return coordinates of the point located at the given length on the given path.
Parameters
Returns: object representation of the point:
Parses colour string as RGB object
Parameters
red”, “green”, “cornflowerblue”, etc)#000”, “#fc0”, etc)#000000”, “#bd2300”)rgb(200, 100, 0)”)rgb(100%, 175%, 0%)”)hsb(0.5, 0.25, 1)”)Returns: object RGB object in format:
Return subpath of a given path from given length to given length.
Parameters
Returns: string pathstring for the segment
Returns length of the given path in pixels.
Parameters
Returns: number length.
Converts HSB values to hex representation of the colour.
Parameters
Returns: string hex representation of the colour.
Converts HSB values to RGB object.
Parameters
Returns: object RGB object in format:
Converts HSL values to hex representation of the colour.
Parameters
Returns: string hex representation of the colour.
Converts HSL values to RGB object.
Parameters
Returns: object RGB object in format:
Handfull replacement for typeof operator.
Parameters
Returns: boolean is given value is of given type
Utility method Returns matrix based on given parameters.
Parameters
Returns: object Matrix
If you want to leave no trace of Raphaël (Well, Raphaël creates only one global variable Raphael, but anyway.) You can use ninja method.
Beware, that in this case plugins could stop working, because they are depending on global variable existance.
Returns: object Raphael object
Usage
(function (local_raphael) {
var paper = local_raphael(10, 10, 320, 200);
…
})(Raphael.ninja());
Utility method Parses given path string into an array of arrays of path segments.
Parameters
Returns: array array of segments.
Utility method Parses given path string into an array of transformations.
Parameters
Returns: array array of transformations.
Utility method Converts path to a new path where all segments are cubic bezier curves.
Parameters
Returns: array array of segments.
Utility method Converts path to relative form
Parameters
Returns: array array of segments.
Transform angle to radians
Parameters
Returns: number angle in radians.
Adds given font to the registered set of fonts for Raphaël. Should be used as an internal call from within Cufón’s font file. Returns original parameter, so it could be used with chaining.
More about Cufón and how to convert your font form TTF, OTF, etc to JavaScript file.Parameters
Returns: object the font you passed in
Usage
Cufon.registerFont(Raphael.registerFont({…}));
Converts RGB values to hex representation of the colour.
Parameters
Returns: string hex representation of the colour.
Converts RGB values to HSB object.
Parameters
Returns: object HSB object in format:
Converts RGB values to HSL object.
Parameters
Returns: object HSL object in format:
Used when you need to draw in <iframe>. Switched window to the iframe one.
Parameters
Snaps given value to given grid.
Parameters
10.Returns: number adjusted value.
You can add your own method to elements and sets. It is wise to add a set method for each element method you added, so you will be able to call the same method on sets too. See also Raphael.el.
Usage
Raphael.el.red = function () {
this.attr({fill: "#f00"});
};
Raphael.st.red = function () {
this.forEach(function () {
this.red();
});
};
// then use it
paper.set(paper.circle(100, 100, 20), paper.circle(110, 100, 20)).red();
true if browser supports SVG.
Can be “SVG”, “VML” or empty, depending on browser support.
true if browser supports VML.
Removeds all elements from the set
Removes given element from the set
Parameters
Returns: boolean true if object was found & removed from the set
Executes given function for each element in the set.
If function returns false it will stop loop running.
Parameters
Returns: object Set object
Removes last element and returns it.
Returns: object element
Adds each argument to the current set.
Returns: object original element
Removes given element from the set
Parameters
Returns: object set elements that were deleted
Fires event with given name, given scope and other parameters.
Arguments
.) or slash (/) separatedReturns: object array of returned values from the listeners
Internal method which gives you array of all event handlers that will be triggered by the given name.
Arguments
.) or slash (/) separatedReturns: array array of event handlers
Could be used inside event handler to figure out actual name of the event.
Arguments
Returns: string name of the event, if subname is not specified
or
Returns: boolean true, if current event’s name contains subname
Binds given event handler with a given name. You can use wildcards “*” for the names:
eve.on("*.under.*", f);
eve("mouse.under.floor"); // triggers f
Use eve to trigger the listener.
Arguments
.) or slash (/) separated, with optional wildcardsReturns: function returned function accept one number parameter that represents z-index of the handler. It is optional feature and only used when you need to ensure that some subset of handlers will be invoked in a given order, despite of the order of assignment.
Example:
eve.on("mouse", eat)(2);
eve.on("mouse", scream);
eve.on("mouse", catch)(1);
This will ensure that catch function will be called before eat.
If you want to put you hadler before not indexed handlers specify negative value.
Note: I assume most of the time you don’t need to worry about z-index, but it’s nice to have this feature “just in case”.
Is used inside event handler to stop event
Removes given function from the list of event listeners assigned to given name.
Arguments
.) or slash (/) separated, with optional wildcardsCurrent version of the library.