# Raphaël Reference

## Animation⚓

### Animation.delay(delay)⚓➭

Creates a copy of existing animation object with given delay.

Parameters

delay
  number
  number of ms to pass between animation start and actual animation

Returns: object new altered Animation object

    var anim = Raphael.animation({cx: 10, cy: 20}, 2e3);
    circle1.animate(anim); // run the given animation immediately
    circle2.animate(anim.delay(500)); // run the given animation after 500 ms

### Animation.repeat(repeat)⚓➭

Creates a copy of existing animation object with given repetition.

Parameters

repeat
  number
  number iterations of animation. For infinite animation pass `Infinity`

Returns: object new altered Animation object

## Element⚓

### Element.animate(…)⚓➭

Creates and starts animation for given element.

Parameters

params
  object
  final attributes for the element, see also Element.attr
ms
  number
  number of milliseconds for animation to run
easing
  optional
  string
  easing type. Accept one of Raphael.easing_formulas or CSS format: `cubic‐bezier(XX, XX, XX, XX)`
callback
  optional
  function
  callback function. Will be called at the end of animation.

or

animation
  object
  animation object, see Raphael.animation

Returns: object original element

### Element.animateWith(…)⚓➭

Acts similar to Element.animate, but ensure that given animation runs in sync with another given element.

Parameters

element
  object
  element to sync with
anim
  object
  animation to sync with
params
  optional
  object
  final attributes for the element, see also Element.attr
ms
  optional
  number
  number of milliseconds for animation to run
easing
  optional
  string
  easing type. Accept on of Raphael.easing_formulas or CSS format: `cubic‐bezier(XX, XX, XX, XX)`
callback
  optional
  function
  callback function. Will be called at the end of animation.

or

element
  object
  element to sync with
anim
  object
  animation to sync with
animation
  optional
  object
  animation object, see Raphael.animation

Returns: object original element

### Element.attr(…)⚓➭

Sets the attributes of the element.

Parameters

attrName
  string
  attribute’s name
value
  string
  value

or

params
  object
  object of name/value pairs

or

attrName
  string
  attribute’s name

or

attrNames
  array
  in this case method returns array of current values for given attribute names

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.

1. arrow-end string arrowhead on the end of the path. The format for string is `<type>[-<width>[-<length>]]`. Possible types: `classic`, `block`, `open`, `oval`, `diamond`, `none`, width: `wide`, `narrow`, `midium`, length: `long`, `short`, `midium`.
2. clip-rect string comma or space separated values: x, y, width and height
3. cursor string CSS type of the cursor
4. cx number the x-axis coordinate of the center of the circle, or ellipse
5. cy number the y-axis coordinate of the center of the circle, or ellipse
6. fill string colour, gradient or image
7. fill-opacity number
8. font string
9. font-family string
10. font-size number font size in pixels
11. font-weight string
12. height number
13. href string URL, if specified element behaves as hyperlink
14. opacity number
15. path string SVG path string format
16. r number radius of the circle, ellipse or rounded corner on the rect
17. rx number horisontal radius of the ellipse
18. ry number vertical radius of the ellipse
19. src string image URL, only works for Element.image element
20. stroke string stroke colour
21. stroke-dasharray string[“”, “`-`”, “`.`”, “`-.`”, “`-..`”, “`.` ”, “`-` ”, “`--`”, “`- .`”, “`--.`”, “`--..`”]
22. stroke-linecap string[“`butt`”, “`square`”, “`round`”]
23. stroke-linejoin string[“`bevel`”, “`round`”, “`miter`”]
24. stroke-miterlimit number
25. stroke-opacity number
26. stroke-width number stroke width in pixels, default is '1'
27. target string used with href
28. text string contents of the text element. Use `\n` for multiline text
29. text-anchor string[“`start`”, “`middle`”, “`end`”], default is “`middle`”
30. title string will create tooltip with a given text
31. transform string see Element.transform
32. width number
33. x number
34. y number

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

- Colour name (“`red`”, “`green`”, “`cornflowerblue`”, etc)
- #••• — shortened HTML colour: (“`#000`”, “`#fc0`”, etc)
- #•••••• — full length HTML colour: (“`#000000`”, “`#bd2300`”)
- rgb(•••, •••, •••) — red, green and blue channels’ values: (“`rgb(200, 100, 0)`”)
- rgb(•••%, •••%, •••%) — same as above, but in %: (“`rgb(100%, 175%, 0%)`”)
- rgba(•••, •••, •••, •••) — red, green and blue channels’ values: (“`rgba(200, 100, 0, .5)`”)
- rgba(•••%, •••%, •••%, •••%) — same as above, but in %: (“`rgba(100%, 175%, 0%, 50%)`”)
- hsb(•••, •••, •••) — hue, saturation and brightness values: (“`hsb(0.5, 0.25, 1)`”)
- hsb(•••%, •••%, •••%) — same as above, but in %
- hsba(•••, •••, •••, •••) — same as above, but with opacity
- hsl(•••, •••, •••) — almost the same as hsb, see Wikipedia page
- hsl(•••%, •••%, •••%) — same as above, but in %
- hsla(•••, •••, •••, •••) — same as above, but with opacity
- Optionally for hsb and hsl you could specify hue as a degree: “`hsl(240deg, 1, .5)`” or, if you want to go fancy, “`hsl(240°, 1, .5)`”

### Element.click(handler)⚓➭

Adds event handler for click for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.clone()⚓➭

Returns: object clone of a given element

### Element.data(key, [value])⚓➭

Adds or retrieves given value asociated with given key. See also Element.removeData

Parameters

key
  string
  key to store data
value
  optional
  any
  value to store

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"));
             });
    }

### Element.dblclick(handler)⚓➭

Adds event handler for double click for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.drag(onmove, onstart, onend, [mcontext], [scontext], [econtext])⚓➭

Adds event handlers for drag of the element.

Parameters

onmove
  function
  handler for moving
onstart
  function
  handler for drag start
onend
  function
  handler for drag end
mcontext
  optional
  object
  context for moving handler
scontext
  optional
  object
  context for drag start handler
econtext
  optional
  object
  context for drag end handler

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:

1. x number x position of the mouse
2. y number y position of the mouse
3. event object DOM event object

Move event and move handler will be called in specified context or in context of the element with following parameters:

1. dx number shift by x from the start point
2. dy number shift by y from the start point
3. x number x position of the mouse
4. y number y position of the mouse
5. event object DOM event object

End event and end handler will be called in specified context or in context of the element with following parameters:

1. event object DOM event object

Returns: object Element

### Element.getBBox(isWithoutTransform)⚓➭

Return bounding box for a given element

Parameters

isWithoutTransform
  boolean
  flag, `true` if you want to have bounding box before transformations. Default is `false`.

Returns: object Bounding box object:

1. {
   1. x:number top left corner x
   2. y:number top left corner y
   3. width:number width
   4. height:number height
2. }

### Element.getPointAtLength(length)⚓➭

Return coordinates of the point located at the given length on the given path. Only works for element of “path” type.

Parameters

length
  number

Returns: object representation of the point:

1. {
   1. x:number x coordinate
   2. y:number y coordinate
   3. alpha:number angle of derivative
2. }

### Element.getSubpath(from, to)⚓➭

Return subpath of a given element from given length to given length. Only works for element of “path” type.

Parameters

from
  number
  position of the start of the segment
to
  number
  position of the end of the segment

Returns: string pathstring for the segment

### Element.getTotalLength()⚓➭

Returns length of the path in pixels. Only works for element of “path” type.

Returns: number length.

### Element.glow([glow])⚓➭

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

glow
  optional
  object
  parameters object with all properties optional:

1. {
   1. width number size of the glow, default is `10`
   2. fill boolean will it be filled, default is `false`
   3. opacity number opacity, default is `0.5`
   4. offsetx number horizontal offset, default is `0`
   5. offsety number vertical offset, default is `0`
   6. color string glow colour, default is `black`
2. }

Returns: object Paper.set of elements that represents glow

### Element.hide()⚓➭

Makes element invisible. See Element.show.

Returns: object Element

### Element.hover(f_in, f_out, [icontext], [ocontext])⚓➭

Adds event handlers for hover for the element.

Parameters

f_in
  function
  handler for hover in
f_out
  function
  handler for hover out
icontext
  optional
  object
  context for hover in handler
ocontext
  optional
  object
  context for hover out handler

Returns: object Element

### Element.id⚓➭

number

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.

### Element.insertAfter()⚓➭

Inserts current object after the given one.

Returns: object Element

### Element.insertBefore()⚓➭

Inserts current object before the given one.

Returns: object Element

### Element.mousedown(handler)⚓➭

Adds event handler for mousedown for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.mousemove(handler)⚓➭

Adds event handler for mousemove for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.mouseout(handler)⚓➭

Adds event handler for mouseout for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.mouseover(handler)⚓➭

Adds event handler for mouseover for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.mouseup(handler)⚓➭

Adds event handler for mouseup for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.next⚓➭

object

Reference to the next element in the hierarchy.

### Element.node⚓➭

object

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");
    };

### Element.onDragOver(f)⚓➭

Shortcut for assigning event handler for `drag.over.<id>` event, where id is id of the element (see Element.id).

Parameters

f
  function
  handler for event, first argument would be the element you are dragging over

### Element.paper⚓➭

object

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"});
    }

### Element.pause([anim])⚓➭

Stops animation of the element with ability to resume it later on.

Parameters

anim
  optional
  object
  animation object

Returns: object original element

### Element.prev⚓➭

object

Reference to the previous element in the hierarchy.

### Element.raphael⚓➭

object

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});
    }

### Element.remove()⚓➭

Removes element form the paper.

### Element.removeData([key])⚓➭

Removes value associated with an element by given key. If key is not provided, removes all the data of the element.

Parameters

key
  optional
  string
  key

Returns: object Element

### Element.resume([anim])⚓➭

Resumes animation if it was paused with Element.pause method.

Parameters

anim
  optional
  object
  animation object

Returns: object original element

### Element.rotate(deg, [cx], [cy])⚓➭

Adds rotation by given angle around given point to the list of transformations of the element.

Parameters

deg
  number
  angle in degrees
cx
  optional
  number
  x coordinate of the centre of rotation
cy
  optional
  number
  y coordinate of the centre of rotation

If cx & cy aren’t specified centre of the shape is used as a point of rotation.

Returns: object Element

### Element.scale(sx, sy, [cx], [cy])⚓➭

Adds scale by given amount relative to given point to the list of transformations of the element.

Parameters

sx
  number
  horisontal scale amount
sy
  number
  vertical scale amount
cx
  optional
  number
  x coordinate of the centre of scale
cy
  optional
  number
  y coordinate of the centre of scale

If cx & cy aren’t specified centre of the shape is used instead.

Returns: object Element

### Element.setTime(anim, value)⚓➭

Sets the status of animation of the element in milliseconds. Similar to Element.status method.

Parameters

anim
  object
  animation object
value
  number
  number of milliseconds from the beginning of the animation

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>`.

### Element.show()⚓➭

Makes element visible. See Element.hide.

Returns: object Element

### Element.status([anim], [value])⚓➭

Gets or sets the status of animation of the element.

Parameters

anim
  optional
  object
  animation object
value
  optional
  number
  0 – 1. If specified, method works like a setter and sets the status of a given animation to the value. This will cause animation to jump to the given position.

Returns: number status

or

Returns: array status if `anim` is not specified. Array of objects in format:

1. {
   1. anim:object animation object
   2. status:number status
2. }

or

Returns: object original element if `value` is specified

### Element.stop([anim])⚓➭

Stops animation of the element.

Parameters

anim
  optional
  object
  animation object

Returns: object original element

### Element.toBack()⚓➭

Moves the element so it is the furthest from the viewer’s eyes, behind other elements.

Returns: object Element

### Element.toFront()⚓➭

Moves the element so it is the closest to the viewer’s eyes, on top of other elements.

Returns: object Element

### Element.touchcancel(handler)⚓➭

Adds event handler for touchcancel for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.touchend(handler)⚓➭

Adds event handler for touchend for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.touchmove(handler)⚓➭

Adds event handler for touchmove for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.touchstart(handler)⚓➭

Adds event handler for touchstart for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.transform([tstr])⚓➭

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.

There are also alternative “absolute” translation, rotation and scale: `T`, `R` and `S`. They will not take previous transformation into account. For example, `...T100,0` will always move element 100 px horisontally, while `...t100,0` could move it vertically if there is `r90` before. Just compare results of `r90t100,0` and `r90T100,0`.

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

tstr
  optional
  string
  transformation string

If tstr isn’t specified

Returns: string current transformation string

else

Returns: object Element

### Element.translate(dx, dy)⚓➭

Adds translation by given amount to the list of transformations of the element.

Parameters

dx
  number
  horisontal shift
dy
  number
  vertical shift

Returns: object Element

### Element.unclick(handler)⚓➭

Removes event handler for click for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.undblclick(handler)⚓➭

Removes event handler for double click for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.undrag()⚓➭

Removes all drag event handlers from given element.

### Element.unhover(f_in, f_out)⚓➭

Removes event handlers for hover for the element.

Parameters

f_in
  function
  handler for hover in
f_out
  function
  handler for hover out

Returns: object Element

### Element.unmousedown(handler)⚓➭

Removes event handler for mousedown for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.unmousemove(handler)⚓➭

Removes event handler for mousemove for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.unmouseout(handler)⚓➭

Removes event handler for mouseout for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.unmouseover(handler)⚓➭

Removes event handler for mouseover for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.unmouseup(handler)⚓➭

Removes event handler for mouseup for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.untouchcancel(handler)⚓➭

Removes event handler for touchcancel for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.untouchend(handler)⚓➭

Removes event handler for touchend for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.untouchmove(handler)⚓➭

Removes event handler for touchmove for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

### Element.untouchstart(handler)⚓➭

Removes event handler for touchstart for the element.

Parameters

handler
  function
  handler for the event

Returns: object Element

## Matrix⚓

### Matrix.add(a, b, c, d, e, f, matrix)⚓➭

Adds given matrix to existing one.

Parameters

a
  number
b
  number
c
  number
d
  number
e
  number
f
  number
matrix
  object
  Matrix

### Matrix.clone()⚓➭

Returns copy of the matrix

Returns: object Matrix

### Matrix.invert()⚓➭

Returns inverted version of the matrix

Returns: object Matrix

### Matrix.rotate(a, x, y)⚓➭

Rotates the matrix

Parameters

a
  number
x
  number
y
  number

### Matrix.scale(x, [y], [cx], [cy])⚓➭

Scales the matrix

Parameters

x
  number
y
  optional
  number
cx
  optional
  number
cy
  optional
  number

### Matrix.split()⚓➭

Splits matrix into primitive transformations

Returns: object in format:

1. dx number translation by x
2. dy number translation by y
3. scalex number scale by x
4. scaley number scale by y
5. shear number shear
6. rotate number rotation in deg
7. isSimple boolean could it be represented via simple transformations

### Matrix.toTransformString()⚓➭

Return transform string that represents given matrix

Returns: string transform string

### Matrix.translate(x, y)⚓➭

Translate the matrix

Parameters

x
  number
y
  number

### Matrix.x(x, y)⚓➭

Return x coordinate for given point after transformation described by the matrix. See also Matrix.y

Parameters

x
  number
y
  number

Returns: number x

### Matrix.y(x, y)⚓➭

Return y coordinate for given point after transformation described by the matrix. See also Matrix.x

Parameters

x
  number
y
  number

Returns: number y

## Paper⚓

### Paper.add(json)⚓➭

Imports elements in JSON array in format `{type: type, <attributes>}`

Parameters

json
  array

Returns: object resulting set of imported elements

Usage

    paper.add([
        {
            type: "circle",
            cx: 10,
            cy: 10,
            r: 5
        },
        {
            type: "rect",
            x: 10,
            y: 10,
            width: 10,
            height: 10,
            fill: "#fc0"
        }
    ]);

### Paper.bottom⚓➭

Points to the bottom element on the paper

### Paper.ca⚓➭

object

Shortcut for Paper.customAttributes

### Paper.circle(x, y, r)⚓➭

Draws a circle.

Parameters

x
  number
  x coordinate of the centre
y
  number
  y coordinate of the centre
r
  number
  radius

Returns: object Raphaël element object with type “circle”

Usage

    var c = paper.circle(50, 50, 40);

### Paper.clear()⚓➭

Clears the paper, i.e. removes all the elements.

### Paper.customAttributes⚓➭

object

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 + ", 0.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: "0.5 .8 1"});
    c.animate({hsb: [1, 0, 0.5]}, 1e3);

### Paper.ellipse(x, y, rx, ry)⚓➭

Draws an ellipse.

Parameters

x
  number
  x coordinate of the centre
y
  number
  y coordinate of the centre
rx
  number
  horizontal radius
ry
  number
  vertical radius

Returns: object Raphaël element object with type “ellipse”

Usage

    var c = paper.ellipse(50, 50, 40, 20);

### Paper.forEach(callback, thisArg)⚓➭

Executes given function for each element on the paper

If callback function returns `false` it will stop loop running.

Parameters

callback
  function
  function to run
thisArg
  object
  context object for the callback

Returns: object Paper object

### Paper.getById(id)⚓➭

Returns you element by its internal ID.

Parameters

id
  number
  id

Returns: object Raphaël element object

### Paper.getElementByPoint(x, y)⚓➭

Returns you topmost element under given point.

Returns: object Raphaël element object

Parameters

x
  number
  x coordinate from the top left corner of the window
y
  number
  y coordinate from the top left corner of the window

Usage

    paper.getElementByPoint(mouseX, mouseY).attr({stroke: "#f00"});

### Paper.getFont(family, [weight], [style], [stretch])⚓➭

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

family
  string
  font family name or any word from it
weight
  optional
  string
  font weight
style
  optional
  string
  font style
stretch
  optional
  string
  font stretch

Returns: object the font object

Usage

    paper.print(100, 100, "Test string", paper.getFont("Times", 800), 30);

### Paper.image(src, x, y, width, height)⚓➭

Embeds an image into the surface.

Parameters

src
  string
  URI of the source image
x
  number
  x coordinate position
y
  number
  y coordinate position
width
  number
  width of the image
height
  number
  height of the image

Returns: object Raphaël element object with type “image”

Usage

    var c = paper.image("apple.png", 10, 10, 80, 80);

### Paper.path([pathString])⚓➭

Creates a path element by given path data string.

Parameters

pathString
  optional
  string
  path string in SVG format.

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

### Paper.print(x, y, text, font, [size], [origin], [letter_spacing])⚓➭

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

x
  number
  x position of the text
y
  number
  y position of the text
text
  string
  text to print
font
  object
  font object, see Paper.getFont
size
  optional
  number
  size of the font, default is `16`
origin
  optional
  string
  could be `"baseline"` or `"middle"`, default is `"middle"`
letter_spacing
  optional
  number
  number in range `-1..1`, default is `0`

Returns: 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"});

### Paper.raphael⚓➭

Points to the Raphael object/function

### Paper.rect(x, y, width, height, [r])⚓➭

Draws a rectangle.

Parameters

x
  number
  x coordinate of the top left corner
y
  number
  y coordinate of the top left corner
width
  number
  width
height
  number
  height
r
  optional
  number
  radius for rounded corners, default is 0

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);

### Paper.remove()⚓➭

Removes the paper from the DOM.

### Paper.renderfix()⚓➭

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.

### Paper.safari()⚓➭

There is an inconvenient rendering bug in Safari (WebKit): sometimes the rendering should be forced. This method should help with dealing with this bug.

### Paper.set()⚓➭

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

### Paper.setFinish()⚓➭

See Paper.setStart. This method finishes catching and returns resulting set.

Returns: object set

### Paper.setSize(width, height)⚓➭

If you need to change dimensions of the canvas call this method

Parameters

width
  number
  new width of the canvas
height
  number
  new height of the canvas

Usage

    var st = paper.set();
    st.push(
        paper.circle(10, 10, 5),
        paper.circle(30, 10, 5)
    );
    st.attr({fill: "red"});

### Paper.setStart()⚓➭

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

### Paper.setViewBox(x, y, w, h, fit)⚓➭

Sets the view box of the paper. Practically it gives you ability to zoom and pan whole paper surface by specifying new boundaries.

Parameters

x
  number
  new x position, default is `0`
y
  number
  new y position, default is `0`
w
  number
  new width of the canvas
h
  number
  new height of the canvas
fit
  boolean
  `true` if you want graphics to fit into new boundary box

### Paper.text(x, y, text)⚓➭

Draws a text string. If you need line breaks, put “\n” in the string.

Parameters

x
  number
  x coordinate position
y
  number
  y coordinate position
text
  string
  The text string to draw

Returns: object Raphaël element object with type “text”

Usage

    var t = paper.text(50, 50, "Raphaël\nkicks\nbutt!");

### Paper.top⚓➭

Points to the topmost element on the paper

## Raphael(…)⚓➭

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

container
  HTMLElement string
  DOM element or its ID which is going to be a parent for drawing surface
width
  number
height
  number
callback
  optional
  function
  callback function which is going to be executed in the context of newly created paper

or

x
  number
y
  number
width
  number
height
  number
callback
  optional
  function
  callback function which is going to be executed in the context of newly created paper

or

all
  array
  (first 3 or 4 elements in the array are equal to [containerID, width, height] or [x, y, width, height]. The rest are element descriptions in format {type: type, <attributes>}). See Paper.add.
callback
  optional
  function
  callback function which is going to be executed in the context of newly created paper

or

onReadyCallback
  function
  function that is going to be called on DOM ready event. You can also subscribe to this event via Eve’s “DOMLoad” event. In this case method returns `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"
    }]);

### Raphael.angle(x1, y1, x2, y2, [x3], [y3])⚓➭

Returns angle between two or three points

Parameters

x1
  number
  x coord of first point
y1
  number
  y coord of first point
x2
  number
  x coord of second point
y2
  number
  y coord of second point
x3
  optional
  number
  x coord of third point
y3
  optional
  number
  y coord of third point

Returns: number angle in degrees.

### Raphael.animation(params, ms, [easing], [callback])⚓➭

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

params
  object
  final attributes for the element, see also Element.attr
ms
  number
  number of milliseconds for animation to run
easing
  optional
  string
  easing type. Accept one of Raphael.easing_formulas or CSS format: `cubic‐bezier(XX, XX, XX, XX)`
callback
  optional
  function
  callback function. Will be called at the end of animation.

Returns: object Animation

### Raphael.color(clr)⚓➭

Parses the color string and returns object with all values for the given color.

Parameters

clr
  string
  color string in one of the supported formats (see Raphael.getRGB)

Returns: object Combined RGB & HSB object in format:

1. {
   1. r number red,
   2. g number green,
   3. b number blue,
   4. hex string color in HTML/CSS format: #••••••,
   5. error boolean `true` if string can’t be parsed,
   6. h number hue,
   7. s number saturation,
   8. v number value (brightness),
   9. l number lightness
2. }

### Raphael.createUUID()⚓➭

Returns RFC4122, version 4 ID

### Raphael.deg(deg)⚓➭

Transform angle to degrees

Parameters

deg
  number
  angle in radians

Returns: number angle in degrees.

### Raphael.easing_formulas⚓➭

Object that contains easing formulas for animation. You could extend it with your own. By default it has following list of easing:

- “linear”
- “<” or “easeIn” or “ease-in”
- “>” or “easeOut” or “ease-out”
- “<>” or “easeInOut” or “ease-in-out”
- “backIn” or “back-in”
- “backOut” or “back-out”
- “elastic”
- “bounce”

See also Easing demo.

### Raphael.el⚓➭

object

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();

### Raphael.findDotsAtSegment(p1x, p1y, c1x, c1y, c2x, c2y, p2x, p2y, t)⚓➭

Utility method Find dot coordinates on the given cubic bezier curve at the given t.

Parameters

p1x
  number
  x of the first point of the curve
p1y
  number
  y of the first point of the curve
c1x
  number
  x of the first anchor of the curve
c1y
  number
  y of the first anchor of the curve
c2x
  number
  x of the second anchor of the curve
c2y
  number
  y of the second anchor of the curve
p2x
  number
  x of the second point of the curve
p2y
  number
  y of the second point of the curve
t
  number
  position on the curve (0..1)

Returns: object point information in format:

1. {
   1. x:number x coordinate of the point
   2. y:number y coordinate of the point
   3. m: {
      1. x:number x coordinate of the left anchor
      2. y:number y coordinate of the left anchor
   4. }
   5. n: {
      1. x:number x coordinate of the right anchor
      2. y:number y coordinate of the right anchor
   6. }
   7. start: {
      1. x:number x coordinate of the start of the curve
      2. y:number y coordinate of the start of the curve
   8. }
   9. end: {
      1. x:number x coordinate of the end of the curve
      2. y:number y coordinate of the end of the curve
   10. }
   11. alpha:number angle of the curve derivative at the point
2. }

### Raphael.fn⚓➭

object

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. You should modify the `fn` object before a Raphaël instance is created, otherwise it will take no effect. Please note that the ability for namespaced plugins was removed in Raphael 2.0. It is up to the plugin to ensure any namespacing ensures proper context.

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();

### Raphael.format(token, …)⚓➭

Simple format function. Replaces construction of type “`{<number>}`” to the corresponding argument.

Parameters

token
  string
  string to format
…
  string
  rest of arguments will be treated as parameters for replacement

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{0},{1}h{2}v{3}h{4}z", x, y, width, height, -width));

### Raphael.fullfill(token, json)⚓➭

A little bit more advanced format function than Raphael.format. Replaces construction of type “`{<name>}`” to the corresponding argument.

Parameters

token
  string
  string to format
json
  object
  object which properties will be used as a replacement

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
        }
    }));

### Raphael.getColor([value])⚓➭

On each call returns next colour in the spectrum. To reset it back to red call Raphael.getColor.reset

Parameters

value
  optional
  number
  brightness, default is `0.75`

Returns: string hex representation of the colour.

#### Raphael.getColor.reset()⚓➭

Resets spectrum position for Raphael.getColor back to red.

### Raphael.getPointAtLength(path, length)⚓➭

Return coordinates of the point located at the given length on the given path.

Parameters

path
  string
  SVG path string
length
  number

Returns: object representation of the point:

1. {
   1. x:number x coordinate
   2. y:number y coordinate
   3. alpha:number angle of derivative
2. }

### Raphael.getRGB(colour)⚓➭

Parses colour string as RGB object

Parameters

colour
  string
  colour string in one of formats:

- Colour name (“`red`”, “`green`”, “`cornflowerblue`”, etc)
- #••• — shortened HTML colour: (“`#000`”, “`#fc0`”, etc)
- #•••••• — full length HTML colour: (“`#000000`”, “`#bd2300`”)
- rgb(•••, •••, •••) — red, green and blue channels’ values: (“`rgb(200, 100, 0)`”)
- rgb(•••%, •••%, •••%) — same as above, but in %: (“`rgb(100%, 175%, 0%)`”)
- hsb(•••, •••, •••) — hue, saturation and brightness values: (“`hsb(0.5, 0.25, 1)`”)
- hsb(•••%, •••%, •••%) — same as above, but in %
- hsl(•••, •••, •••) — same as hsb
- hsl(•••%, •••%, •••%) — same as hsb

Returns: object RGB object in format:

1. {
   1. r number red,
   2. g number green,
   3. b number blue
   4. hex string color in HTML/CSS format: #••••••,
   5. error boolean true if string can’t be parsed
2. }

### Raphael.getSubpath(path, from, to)⚓➭

Return subpath of a given path from given length to given length.

Parameters

path
  string
  SVG path string
from
  number
  position of the start of the segment
to
  number
  position of the end of the segment

Returns: string pathstring for the segment

### Raphael.getTotalLength(path)⚓➭

Returns length of the given path in pixels.

Parameters

path
  string
  SVG path string.

Returns: number length.

### Raphael.hsb(h, s, b)⚓➭

Converts HSB values to hex representation of the colour.

Parameters

h
  number
  hue
s
  number
  saturation
b
  number
  value or brightness

Returns: string hex representation of the colour.

### Raphael.hsb2rgb(h, s, v)⚓➭

Converts HSB values to RGB object.

Parameters

h
  number
  hue
s
  number
  saturation
v
  number
  value or brightness

Returns: object RGB object in format:

1. {
   1. r number red,
   2. g number green,
   3. b number blue,
   4. hex string color in HTML/CSS format: #••••••
2. }

### Raphael.hsl(h, s, l)⚓➭

Converts HSL values to hex representation of the colour.

Parameters

h
  number
  hue
s
  number
  saturation
l
  number
  luminosity

Returns: string hex representation of the colour.

### Raphael.hsl2rgb(h, s, l)⚓➭

Converts HSL values to RGB object.

Parameters

h
  number
  hue
s
  number
  saturation
l
  number
  luminosity

Returns: object RGB object in format:

1. {
   1. r number red,
   2. g number green,
   3. b number blue,
   4. hex string color in HTML/CSS format: #••••••
2. }

### Raphael.is(o, type)⚓➭

Handfull replacement for `typeof` operator.

Parameters

o
  …
  any object or primitive
type
  string
  name of the type, i.e. “string”, “function”, “number”, etc.

Returns: boolean is given value is of given type

### Raphael.matrix(a, b, c, d, e, f)⚓➭

Utility method Returns matrix based on given parameters.

Parameters

a
  number
b
  number
c
  number
d
  number
e
  number
f
  number

Returns: object Matrix

### Raphael.ninja()⚓➭

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());

### Raphael.parsePathString(pathString)⚓➭

Utility method Parses given path string into an array of arrays of path segments.

Parameters

pathString
  string array
  path string or array of segments (in the last case it will be returned straight away)

Returns: array array of segments.

### Raphael.parseTransformString(TString)⚓➭

Utility method Parses given path string into an array of transformations.

Parameters

TString
  string array
  transform string or array of transformations (in the last case it will be returned straight away)

Returns: array array of transformations.

### Raphael.path2curve(pathString)⚓➭

Utility method Converts path to a new path where all segments are cubic bezier curves.

Parameters

pathString
  string array
  path string or array of segments

Returns: array array of segments.

### Raphael.pathToRelative(pathString)⚓➭

Utility method Converts path to relative form

Parameters

pathString
  string array
  path string or array of segments

Returns: array array of segments.

### Raphael.rad(deg)⚓➭

Transform angle to radians

Parameters

deg
  number
  angle in degrees

Returns: number angle in radians.

### Raphael.registerFont(font)⚓➭

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

font
  object
  the font to register

Returns: object the font you passed in

Usage

    Cufon.registerFont(Raphael.registerFont({…}));

### Raphael.rgb(r, g, b)⚓➭

Converts RGB values to hex representation of the colour.

Parameters

r
  number
  red
g
  number
  green
b
  number
  blue

Returns: string hex representation of the colour.

### Raphael.rgb2hsb(r, g, b)⚓➭

Converts RGB values to HSB object.

Parameters

r
  number
  red
g
  number
  green
b
  number
  blue

Returns: object HSB object in format:

1. {
   1. h number hue
   2. s number saturation
   3. b number brightness
2. }

### Raphael.rgb2hsl(r, g, b)⚓➭

Converts RGB values to HSL object.

Parameters

r
  number
  red
g
  number
  green
b
  number
  blue

Returns: object HSL object in format:

1. {
   1. h number hue
   2. s number saturation
   3. l number luminosity
2. }

### Raphael.setWindow(newwin)⚓➭

Used when you need to draw in `<iframe>`. Switched window to the iframe one.

Parameters

newwin
  window
  new window object

### Raphael.snapTo(values, value, [tolerance])⚓➭

Snaps given value to given grid.

Parameters

values
  array number
  given array of values or step of the grid
value
  number
  value to adjust
tolerance
  optional
  number
  tolerance for snapping. Default is `10`.

Returns: number adjusted value.

### Raphael.st⚓➭

object

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();

### Raphael.svg⚓➭

boolean

`true` if browser supports SVG.

### Raphael.type⚓➭

string

Can be “SVG”, “VML” or empty, depending on browser support.

### Raphael.vml⚓➭

boolean

`true` if browser supports VML.

## Set⚓

### Set.clear()⚓➭

Removeds all elements from the set

### Set.exclude(element)⚓➭

Removes given element from the set

Parameters

element
  object
  element to remove

Returns: boolean `true` if object was found & removed from the set

### Set.forEach(callback, thisArg)⚓➭

Executes given function for each element in the set.

If function returns `false` it will stop loop running.

Parameters

callback
  function
  function to run
thisArg
  object
  context object for the callback

Returns: object Set object

### Set.pop()⚓➭

Removes last element and returns it.

Returns: object element

### Set.push()⚓➭

Adds each argument to the current set.

Returns: object original element

### Set.splice(index, count, [insertion…])⚓➭

Removes given element from the set

Parameters

index
  number
  position of the deletion
count
  number
  number of element to remove
insertion…
  optional
  object
  elements to insert

Returns: object set elements that were deleted

## eve(name, scope, varargs)⚓➭

Fires event with given `name`, given scope and other parameters.

Arguments

name
  string
  name of the event, dot (`.`) or slash (`/`) separated
scope
  object
  context for the event handlers
varargs
  ...
  the rest of arguments will be sent to event handlers

Returns: object array of returned values from the listeners

### eve.listeners(name)⚓➭

Internal method which gives you array of all event handlers that will be triggered by the given `name`.

Arguments

name
  string
  name of the event, dot (`.`) or slash (`/`) separated

Returns: array array of event handlers

### eve.nt([subname])⚓➭

Could be used inside event handler to figure out actual name of the event.

Arguments

subname
  optional
  string
  subname of the event

Returns: string name of the event, if `subname` is not specified

or

Returns: boolean `true`, if current event’s name contains `subname`

### eve.on(name, f)⚓➭

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

name
  string
  name of the event, dot (`.`) or slash (`/`) separated, with optional wildcards
f
  function
  event handler function

Returns: function returned function accepts a single numeric parameter that represents z-index of the handler. It is an 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 your handler before non-indexed handlers, specify a 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”.

### eve.once(name, f)⚓➭

Binds given event handler with a given name to only run once then unbind itself.

    eve.once("login", f);
    eve("login"); // triggers f
    eve("login"); // no listeners

Use eve to trigger the listener.

Arguments

name
  string
  name of the event, dot (`.`) or slash (`/`) separated, with optional wildcards
f
  function
  event handler function

Returns: function same return function as eve.on

### eve.stop()⚓➭

Is used inside an event handler to stop the event, preventing any subsequent listeners from firing.

### eve.unbind(name, f)⚓➭

Removes given function from the list of event listeners assigned to given name.

Arguments

name
  string
  name of the event, dot (`.`) or slash (`/`) separated, with optional wildcards
f
  function
  event handler function

### eve.version⚓➭

string

Current version of the library.