Creates a drawing surface or wraps existing SVG element.

or

or

Returns: object Element

Replaces construction of type {<name>} to the corresponding argument

Returns: string formatted string

Usage

// this draws a rectangular shape equivalent to "M10,20h40v50h-40z"
paper.path(Snap.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
    }
}));

Transform angle to radians

Returns: number angle in radians

Transform angle to degrees

Returns: number angle in degrees

Returns an angle between two or three points

Parameters

Returns: number angle in degrees

Handy replacement for the typeof operator

Returns: boolean true if given value is of given type

Snaps given value to given grid

Returns: number adjusted value

Adds the given matrix to existing one

or

Returns an inverted version of the matrix

Returns: object Matrix

Returns a copy of the matrix

Returns: object Matrix

Translate the matrix

Scales the matrix

Default cx, cy is the middle point of the element.

Rotates the matrix

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

Returns: number x

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

Returns: number y

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

Returns transform string that represents given matrix

Returns: string transform string

Utility method Returns a matrix based on the given parameters

or

Returns: object Matrix

Parses color string as RGB object

• Color name (red, green, cornflowerblue, etc)
• #••• — shortened HTML color: (#000, #fc0, etc.)
• #•••••• — full length HTML color: (#000000, #bd2300)
• rgb(•••, •••, •••) — red, green and blue channels values: (rgb(200, 100, 0))
• rgba(•••, •••, •••, •••) — also with opacity
• rgb(•••%, •••%, •••%) — same as above, but in %: (rgb(100%, 175%, 0%))
• rgba(•••%, •••%, •••%, •••%) — also with opacity
• hsb(•••, •••, •••) — hue, saturation and brightness values: (hsb(0.5, 0.25, 1))
• hsba(•••, •••, •••, •••) — also with opacity
• hsb(•••%, •••%, •••%) — same as above, but in %
• hsba(•••%, •••%, •••%, •••%) — also with opacity
• hsl(•••, •••, •••) — hue, saturation and luminosity values: (hsb(0.5, 0.25, 0.5))
• hsla(•••, •••, •••, •••) — also with opacity
• hsl(•••%, •••%, •••%) — same as above, but in %
• hsla(•••%, •••%, •••%, •••%) — also with opacity

Note that % can be used any time: rgb(20%, 255, 50%).

Returns: object RGB object in the following 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. }

Converts HSB values to a hex representation of the color

Returns: string hex representation of the color

Converts HSL values to a hex representation of the color

Returns: string hex representation of the color

Converts RGB values to a hex representation of the color

Returns: string hex representation of the color

Parses the color string and returns an object featuring the color's component values

Returns: object Combined RGB/HSB object in the following 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. }

Converts HSB values to an RGB object

Returns: object RGB object in the following format:

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

Converts HSL values to an RGB object

Returns: object RGB object in the following format:

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

Converts RGB values to an HSB object

Returns: object HSB object in the following format:

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

Converts RGB values to an HSL object

Returns: object HSL object in the following format:

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

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

Returns: array array of segments

Utility method Parses given transform string into an array of transformations

Returns: array array of transformations

Wraps a DOM element specified by CSS selector as Element

Returns: Element the current element

Wraps DOM elements specified by CSS selector as set or array of Element

Returns: Element the current element

Gets or sets given attributes of the element

or

Returns: Element the current element

or

Returns: string value of attribute

Usage

el.attr({
    fill: "#fc0",
    stroke: "#000",
    strokeWidth: 2, // CamelCase...
    "fill-opacity": 0.5 // or dash-separated names
});
console.log(el.attr("fill")); // #fc0

Returns the bounding box descriptor for the given element

Returns: object bounding box descriptor:

1. {
   1. cx: number x of the center,
   2. cy: number x of the center,
   3. h: number height,
   4. height: number height,
   5. path: string path command for the box,
   6. r0: number radius of a circle that fully encloses the box,
   7. r1: number radius of the smallest circle that can be enclosed,
   8. r2: number radius of the largest circle that can be enclosed,
   9. vb: string box as a viewbox command,
   10. w: number width,
   11. width: number width,
   12. x2: number x of the right side,
   13. x: number x of the left side,
   14. y2: number y of the bottom edge,
   15. y: number y of the top edge
2. }

Gets or sets transformation of the element

Returns: Element the current element

or

Returns: object transformation descriptor:

1. {
   1. string string transform string,
   2. globalMatrix Matrix matrix of all transformations applied to element or its parents,
   3. localMatrix Matrix matrix of transformations applied only to the element,
   4. diffMatrix Matrix matrix of difference between global and local transformations,
   5. global string global transformation as string,
   6. local string local transformation as string,
   7. toString function returns string property
2. }

Returns the element's parent

Returns: Element the parent element

Appends the given element to current one

Returns: Element the parent element

See Element.append

Appends the current element to the given one

Returns: Element the child element

Prepends the given element to the current one

Returns: Element the parent element

Prepends the current element to the given one

Returns: Element the child element

Inserts given element before the current one

Returns: Element the parent element

Inserts given element after the current one

Returns: Element the parent element

Inserts the element after the given one

Returns: Element the parent element

Inserts the element after the given one

Returns: Element the parent element

Removes element from the DOM

Returns: Element the detached element

Gathers the nested Element matching the given set of CSS selectors

Returns: Element result of query selection

Gathers nested Element objects matching the given set of CSS selectors

Returns: Set array result of query selection

Returns given attribute of the element as a px value (not %, em, etc.)

Returns: Element result of query selection

Creates a <use> element linked to the current element

Returns: Element the <use> element

Creates a clone of the element and inserts it after the element

Returns: Element the clone

Moves element to the shared <defs> area

Returns: Element the clone

Creates a <pattern> element from the current element To create a pattern you have to specify the pattern rect:

Returns: Element the <pattern> element

You can use pattern later on as an argument for fill attribute:

var p = paper.path("M10-5-10,15M15,0,0,15M0-5-20,15").attr({
        fill: "none",
        stroke: "#bada55",
        strokeWidth: 5
    }).pattern(0, 0, 10, 10),
    c = paper.circle(200, 200, 100);
c.attr({
    fill: p
});

Creates a <marker> element from the current element To create a marker you have to specify the bounding rect and reference point:

Returns: Element the <marker> element

You can specify the marker later as an argument for marker-start, marker-end, marker-mid, and marker attributes. The marker attribute places the marker at every point along the path, and marker-mid places them at every point except the start and end.

Creates an animation object

Returns: object animation object

Returns a set of animations that may be able to manipulate the current element

Returns: object in format:

1. {
   1. anim object animation object,
   2. curStatus number 0..1 — status of the animation: 0 — just started, 1 — just finished,
   3. status function gets or sets the status of the animation,
   4. stop function stops the animation
2. }

Runs generic animation of one number into another with a caring function

Returns: object animation object in mina format

1. {
   1. id string animation id, consider it read-only,
   2. duration function gets or sets the duration of the animation,
   3. easing function easing,
   4. speed function gets or sets the speed of the animation,
   5. status function gets or sets the status of the animation,
   6. stop function stops the animation
2. }

var rect = Snap().rect(0, 0, 10, 10);
Snap.animate(0, 10, function (val) {
    rect.attr({
        x: val
    });
}, 1000);
// in given context is equivalent to
rect.animate({x: 10}, 1000);

Stops all the animations for the current element

Returns: Element the current element

Animates the given attributes of the element

Returns: Element the current element

Adds or retrieves given value associated with given key. (Don’t confuse with data- attributes)

See also Element.removeData

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

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

Returns: object Element

Returns SVG code for the element, equivalent to HTML's outerHTML.

See also Element.innerSVG

Returns: string SVG code for the element

See Element.outerSVG

Returns SVG code for the element's contents, equivalent to HTML's innerHTML

Returns: string SVG code for the element

Parses SVG fragment and converts it into a Fragment

Returns: Fragment the Fragment

See Element.select

See Element.selectAll

Creates a DOM fragment from a given list of elements or strings

Returns: Fragment the Fragment

Creates an element on paper with a given name and no attributes

Returns: Element the current element

Usage

var c = paper.circle(10, 10, 10); // is the same as...
var c = paper.el("circle").attr({
    cx: 10,
    cy: 10,
    r: 10
});
// and the same as
var c = paper.el("circle", {
    cx: 10,
    cy: 10,
    r: 10
});

Draws a rectangle

Returns: object the rect element

Usage

// regular rectangle
var c = paper.rect(10, 10, 50, 50);
// rectangle with rounded corners
var c = paper.rect(40, 40, 50, 50, 10);

Draws a circle

Returns: object the circle element

Usage

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

Places an image on the surface

Returns: object the image element

or

Returns: object Snap element object with type image

Usage

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

Draws an ellipse

Returns: object the ellipse element

Usage

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

Creates a <path> element using the given string as the path's definition

Path string consists of one-letter commands, followed by comma seprarated arguments in numerical form. Example:

"M10,20L30,40"

This example features two commands: M, with arguments (10, 20) and L with arguments (30, 40). Uppercase letter commands express coordinates in absolute terms, while lowercase commands express them in relative terms from the most recently declared coordinates.

Here is short list of commands available, for more details see SVG path string format or article about path strings at MDN.

Usage

var c = paper.path("M10 10L90 90");
// draw a diagonal line:
// move to 10,10, line to 90,90

Creates a group element

Returns: object the g element

Usage

var c1 = paper.circle(),
    c2 = paper.rect(),
    g = paper.g(c2, c1); // note that the order of elements is different

or

var c1 = paper.circle(),
    c2 = paper.rect(),
    g = paper.g();
g.add(c2, c1);

See Paper.g

Draws a text string

Returns: object the text element

Usage

var t1 = paper.text(50, 50, "Snap");
var t2 = paper.text(50, 50, ["S","n","a","p"]);
// Text path usage
t1.attr({textpath: "M10,10L100,100"});
// or
var pth = paper.path("M10,10L100,100");
t1.attr({textpath: pth});

Draws a line

Returns: object the line element

Usage

var t1 = paper.line(50, 50, 100, 100);

Draws a polyline

or

Returns: object the polyline element

Usage

var p1 = paper.polyline([10, 10, 100, 100]);
var p2 = paper.polyline(10, 10, 100, 100);

Draws a polygon. See Paper.polyline

Creates a gradient element

Gradient Descriptor

The gradient descriptor is an expression formatted as follows: <type>(<coords>)<colors>. The <type> can be either linear or radial. The uppercase L or R letters indicate absolute coordinates offset from the SVG surface. Lowercase l or r letters indicate coordinates calculated relative to the element to which the gradient is applied. Coordinates specify a linear gradient vector as x1, y1, x2, y2, or a radial gradient as cx, cy, r and optional fx, fy specifying a focal point away from the center of the circle. Specify <colors> as a list of dash-separated CSS color values. Each color may be followed by a custom offset value, separated with a colon character.

Examples

Linear gradient, relative from top-left corner to bottom-right corner, from black through red to white:

var g = paper.gradient("l(0, 0, 1, 1)#000-#f00-#fff");

Linear gradient, absolute from (0, 0) to (100, 100), from black through red at 25% to white:

var g = paper.gradient("L(0, 0, 100, 100)#000-#f00:25%-#fff");

Radial gradient, relative from the center of the element with radius half the width, from black to white:

var g = paper.gradient("r(0.5, 0.5, 0.5)#000-#fff");

To apply the gradient:

paper.circle(50, 50, 40).attr({
    fill: g
});

Returns: object the gradient element

Returns SVG code for the Paper

Returns: string SVG code for the Paper

Removes all child nodes of the paper, except <defs>.

Simple implementation of Ajax

or

Returns: XMLHttpRequest the XMLHttpRequest object, just in case

Loads external SVG file as a Fragment (see Snap.ajax for more advanced AJAX)

Returns you topmost element under given point.

Returns: object Snap element object

Usage

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

Let you write plugins. You pass in a function with four arguments, like this:

Snap.plugin(function (Snap, Element, Paper, global) {
    Snap.newmethod = function () {};
    Element.prototype.newmethod = function () {};
    Paper.prototype.newmethod = function () {};
});

Inside the function you have access to all main objects (and their prototypes). This allow you to extend anything you want.

Generic animation of numbers

Returns: object animation descriptor

1. {
   1. id string animation id,
   2. start number start slave number,
   3. end number end slave number,
   4. b number start master number,
   5. s number animation status (0..1),
   6. dur number animation duration,
   7. spd number animation speed,
   8. get function getter of master number (see mina.time),
   9. set function setter of slave number,
   10. easing function easing function, default is mina.linear,
   11. status function status getter/setter,
   12. speed function speed getter/setter,
   13. duration function duration getter/setter,
   14. stop function animation stopper
2. }

Returns the current time. Equivalent to:

function () {
    return (new Date).getTime();
}

Returns an animation by its id

Returns: object See mina

Default linear easing

Returns: number output 0..1

Easeout easing

Returns: number output 0..1

Easein easing

Returns: number output 0..1

Easeinout easing

Returns: number output 0..1

Backin easing

Returns: number output 0..1

Backout easing

Returns: number output 0..1

Elastic easing

Returns: number output 0..1

Bounce easing

Returns: number output 0..1

Creates a <filter> element

Returns: object Element

Note: It is recommended to use filters embedded into the page inside an empty SVG element.

Usage

var f = paper.filter(''),
    c = paper.circle(10, 10, 10).attr({
        filter: f
    });

Returns an SVG markup string for the blur filter

Returns: string filter representation

Usage

var f = paper.filter(Snap.filter.blur(5, 10)),
    c = paper.circle(10, 10, 10).attr({
        filter: f
    });

Returns an SVG markup string for the shadow filter

Returns: string filter representation

Usage

var f = paper.filter(Snap.filter.shadow(0, 2, 3)),
    c = paper.circle(10, 10, 10).attr({
        filter: f
    });

Returns an SVG markup string for the grayscale filter

Returns: string filter representation

Returns an SVG markup string for the sepia filter

Returns: string filter representation

Returns an SVG markup string for the saturate filter

Returns: string filter representation

Returns an SVG markup string for the hue-rotate filter

Returns: string filter representation

Returns an SVG markup string for the invert filter

Returns: string filter representation

Returns an SVG markup string for the brightness filter

Returns: string filter representation

Returns an SVG markup string for the contrast filter

Returns: string filter representation

Adds a click event handler to the element

Returns: object Element

Removes a click event handler from the element

Returns: object Element

Adds a double click event handler to the element

Returns: object Element

Removes a double click event handler from the element

Returns: object Element

Adds a mousedown event handler to the element

Returns: object Element

Removes a mousedown event handler from the element

Returns: object Element

Adds a mousemove event handler to the element

Returns: object Element

Removes a mousemove event handler from the element

Returns: object Element

Adds a mouseout event handler to the element

Returns: object Element

Removes a mouseout event handler from the element

Returns: object Element

Adds a mouseover event handler to the element

Returns: object Element

Removes a mouseover event handler from the element

Returns: object Element

Adds a mouseup event handler to the element

Returns: object Element

Removes a mouseup event handler from the element

Returns: object Element

Adds a touchstart event handler to the element

Returns: object Element

Removes a touchstart event handler from the element

Returns: object Element

Adds a touchmove event handler to the element

Returns: object Element

Removes a touchmove event handler from the element

Returns: object Element

Adds a touchend event handler to the element

Returns: object Element

Removes a touchend event handler from the element

Returns: object Element

Adds a touchcancel event handler to the element

Returns: object Element

Removes a touchcancel event handler from the element

Returns: object Element

Adds hover event handlers to the element

Returns: object Element

Removes hover event handlers from the element

Returns: object Element

Adds event handlers for an element's drag gesture

Additionaly following drag events are triggered: drag.start.<id> on start, drag.end.<id> on end and drag.move.<id> on every move. When element is dragged over another element drag.over.<id> fires as well.

Start event and start handler are 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 are 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 are called in specified context or in context of the element with following parameters:

1. event object DOM event object

Returns: object Element

Removes all drag event handlers from the given element

Returns the length of the given path in pixels

Returns: number length

Returns the coordinates of the point located at the given length along the given path

Returns: object representation of the point:

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

Returns the subpath of a given path between given start and end lengths

Returns: string path string definition for the segment

Returns the length of the path in pixels (only works for path elements)

Returns: number length

Returns coordinates of the point located at the given length on the given path (only works for path elements)

Returns: object representation of the point:

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

Returns subpath of a given element from given start and end lengths (only works for path elements)

Returns: string path string definition for the segment

Utility method Finds dot coordinates on the given cubic beziér curve at the given t

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

Utility method Returns the bounding box of a given cubic beziér curve

or

Returns: object bounding box

1. {
   1. x: number x coordinate of the left top point of the box,
   2. y: number y coordinate of the left top point of the box,
   3. x2: number x coordinate of the right bottom point of the box,
   4. y2: number y coordinate of the right bottom point of the box,
   5. width: number width of the box,
   6. height: number height of the box
2. }

Utility method Returns true if given point is inside bounding box

Returns: boolean true if point is inside

Utility method Returns true if two bounding boxes intersect

Returns: boolean true if bounding boxes intersect

Utility method Finds intersections of two paths

Returns: array dots of intersection

1. [
2. {
   1. x: number x coordinate of the point,
   2. y: number y coordinate of the point,
   3. t1: number t value for segment of path1,
   4. t2: number t value for segment of path2,
   5. segment1: number order number for segment of path1,
   6. segment2: number order number for segment of path2,
   7. bez1: array eight coordinates representing beziér curve for the segment of path1,
   8. bez2: array eight coordinates representing beziér curve for the segment of path2
3. }
4. ]

Utility method Returns true if given point is inside a given closed path.

Note: fill mode doesn’t affect the result of this method.

Returns: boolean true if point is inside the path

Utility method Returns the bounding box of a given path

Returns: object bounding box

1. {
   1. x: number x coordinate of the left top point of the box,
   2. y: number y coordinate of the left top point of the box,
   3. x2: number x coordinate of the right bottom point of the box,
   4. y2: number y coordinate of the right bottom point of the box,
   5. width: number width of the box,
   6. height: number height of the box
2. }

Utility method Converts path coordinates into relative values

Returns: array path string

Utility method Converts path coordinates into absolute values

Returns: array path string

Utility method Converts path to a new path where all segments are cubic beziér curves

Returns: array array of segments

Transform the path string with the given matrix

Returns: string transformed path string

Adds each argument to the current set

Returns: object original element

Removes last element and returns it

Returns: object element

Executes given function for each element in the set

If the function returns false, the loop stops running.

Returns: object Set object

Removes all elements from the set

Removes range of elements from the set

Returns: object set elements that were deleted

Removes given element from the set

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