Attributes

attr() as setter

returns itself
animate yes (only for numbers, arrays, colors, ...)

Set a single attribute:

rect.attr('x', 50)

Set multiple attributes at once:

rect.attr({
  fill: '#f06'
, 'fill-opacity': 0.5
, stroke: '#000'
, 'stroke-width': 10
})

Set an attribute with a namespace:

rect.attr('x', 50, 'http://www.w3.org/2000/svg')

Explicitly remove an attribute:

rect.attr('fill', null)

attr() as getter

returns value (string, number, ...)

You can get and set an element's attributes directly using attr().

Get a single attribute:

var x = rect.attr('x')

Get all attributes as an object:

var attributes = rect.attr()

Positioning

While positioning an element by directly setting its attributes works only if the attributes are used natively by that type of element, the positioning methods described below are much more convenient as they work for all element types.

For example, the following code works because each element is positioned by setting native attributes:

rect.attr({ x: 20, y: 60 })
circle.attr({ cx: 50, cy: 40 })

The rect will be moved by its upper left corner to the new coordinates, and the circle will be moved by its centre. However, trying to move a circle by its 'corner' or a rect by its centre in this way will fail. The following lines will get silently ignored as the attributes that are addressed are not natively used by the element setting them:

rect.attr({ cx: 20, cy: 60 })
circle.attr({ x: 50, y: 40 })

However, the positioning methods detailed below will work for all element types, regardless of whether the attributes being addressed are native to the type. So, unlike the lines above, these lines work just fine:

rect.cx(20).cy(60)
circle.x(50).y(40)

It is important to note, though, that these methods are only intended for use with user (unitless) coordinates. If for example, an element has its size set via percentages or other units, the positioning methods that address its native attributes will most likely still work, but the ones that address non-native attributes will give unexpected results -- as both getters and setters!

move()

returns itself
animate yes

Move the element by its upper left corner to a given x and y position:

rect.move(200, 350)

x() as setter

returns itself
animate yes

Move the element by its upper left corner along the x-axis only:

rect.x(200)

x() as getter

returns value

Without an argument the x() method serves as a getter:

var x = rect.x()

y() as setter

returns itself
animate yes

Move the element by its upper left corner along the y-axis only:

rect.y(350)

y() as getter

returns value

Without an argument the y() method serves as a getter:

var y = rect.y()

center()

returns itself
animate yes

Move the element by its center to a given cx and cy position:

rect.center(150, 150)

cx() as setter

returns itself
animate yes

Move the element by its centre in the x direction only:

rect.cx(200)

cx() as getter

returns value

Without an argument the cx() method serves as a getter:

var cx = rect.cx()

cy() as setter

returns itself
animate yes

Move the element by its centre in the y direction only:

rect.cy(350)

cy() as getter

returns value

Without an argument the cy() method serves as a getter as well:

var cy = rect.cy()

dmove()

returns itself
animate yes

Shift the element in both the x and y directions relative to its current position:

rect.dmove(10, 30)

Note: when using dmove() (and dx() or dy() too for that matter), always make sure you provide values of the same unit the element is originally positioned in. So if the element is at x:10%, use element.dx('5%') and not element.dx('5px').

dx()

returns itself
animate yes

Shift the element in the x direction relative to its current position:

rect.dx(200)

dy()

returns itself
animate yes

Shift the element in the y direction relative to its current position:

rect.dy(200)

Resizing

size()

returns itself
animate yes

Set the size of an element to a given width and height:

rect.size(200, 300)

Proportional resizing is also possible by leaving out height:

rect.size(200)

Or by passing null as the value for width:

rect.size(null, 200)

As with positioning, the size of an element could be set by using attr(). But because every type of element is handles its size differently the size() method is much more convenient.

There is one exception though: for SVG.Text elements, this method takes only one argument and applies the given value to the font-size attribute.

width() as setter

returns itself
animate yes

Set the width of an element:

rect.width(200)

width() as getter

returns value

var width = rect.width()

height() as setter

returns itself
animate yes

Set the height of an element:

rect.height(325)

height() as getter

returns value

rect.height()

radius()

returns itself
animate yes

Circles, ellipses, and rects may use the radius() method. On rects, it defines rounded corners.

For a circle, the argument sets the r attribute.

circle.radius(10)

For ellipses and rects, pass two arguments to set the rx and ry attributes individually. Or, pass a single argument, to make the two attributes equal.

ellipse.radius(10, 20)
rect.radius(5)

Syntactic sugar

fill()

returns itself

The fill() method is a pretty alternative to the attr() method:

rect.fill({ color: '#f06', opacity: 0.6 })

A single hex string will work as well:

rect.fill('#f06')

Last but not least, you can also use an image as fill, simply by passing an image url:

rect.fill('images/shade.jpg')

Or if you want more control over the size of the image, you can pass an image instance as well:

rect.fill(draw.image('images/shade.jpg', 20, 20))

stroke()

returns itself

The stroke() method is similar to fill():

rect.stroke({ color: '#f06', opacity: 0.6, width: 5 })

Like fill, a single hex string will work as well:

rect.stroke('#f06')

Not unlike the fill() method, you can also use an image as stroke, simply by passing an image url:

rect.stroke('images/shade.jpg')

Or if you want more control over the size of the image, you can pass an image instance as well:

rect.stroke(draw.image('images/shade.jpg', 20, 20))

opacity()

returns itself

To set the overall opacity of an element:

rect.opacity(0.5)

Transforming

transform() as setter

returns itself
animate yes

As a setter it has two ways of working. By default transformations are absolute. For example, if you call:

element.transform({ rotation: 125 }).transform({ rotation: 37.5 })

The resulting rotation will be 37.5 and not the sum of the two transformations. But if that's what you want there is a way out by adding the relative parameter. That would be:

element.transform({ rotation: 125 }).transform({ rotation: 37.5, relative: true })

Alternatively a relative flag can be passed as the second argument:

element.transform({ rotation: 125 }).transform({ rotation: 37.5 }, true)

Available transformations are:

rotation with optional cx and cy
scale with optional cx and cy
scaleX with optional cx and cy
scaleY with optional cx and cy
skewX with optional cx and cy
skewY with optional cx and cy
x
y
a, b, c, d, e and/or f or an existing matrix instead of the object

transform() as getter

returns value

The transform() method acts as a full getter without an argument:

element.transform()

The returned object contains the following values:

x (translation on the x-axis)
y (translation on the y-axis)
skewX (calculated skew on x-axis)
skewY (calculated skew on y-axis)
scaleX (calculated scale on x-axis)
scaleY (calculated scale on y-axis)
rotation (calculated rotation)
cx (last used rotation centre on x-axis)
cy (last used rotation centre on y-axis)

Additionally a string value for the required property can be passed:

element.transform('rotation')

flip()

returns itself
animate yes

Flips element over a given axis:

element.flip('x')

element.flip('y')

By default, elements are flipped over their centre point. The flip axis position can be defined with the second argument:

element.flip('x', 150)

element.flip('y', 100)

Finally, an element can also be flipped over two axes at once by not providing an axis value:

element.flip()

And flipping on both axes at the same offset can be done by passing only a numeric value:

element.flip(5)

rotate()

returns itself
animate yes

The rotate() method will automatically rotate elements according to the center of the element:

// rotate(degrees)
element.rotate(45)

Although you can also define a specific rotation point:

// rotate(degrees, cx, cy)
element.rotate(45, 50, 50)

skew()

returns itself
animate yes

The skew() method will take an x and y value:

// skew(x, y)
element.skew(0, 45)

scale()

returns itself
animate yes

The scale() method will scale elements by multiplying their x and y
coordinates by either a single scale factor or two separate scale factors:

// scale(factor)
element.scale(2)
// scale(xFactor, yFactor)
element.scale(0.5, -1)

By default, scaling is relative to the center of the element.
You can also define a specific center point (vanishing point of scaling):

// scale(factor, centerX, centerY)
element.scale(2, 0, 0)
// scale(xFactor, yFactor, centerX, centerY)
element.scale(0.5, -1, 0, 0)

translate()

returns itself
animate yes

The translate() method will take an x and y value:

// translate(x, y)
element.translate(0.5, -1)

Styles

style() as setter

returns itself

With the style() method the style attribute can be managed like attributes with attr:

element.style('cursor', 'pointer')

Multiple styles can be set at once using an object:

element.style({ cursor: 'pointer', fill: '#f03' })

Or a css string:

element.style('cursor:pointer;fill:#f03;')

Explicitly deleting individual style definitions works the same as with the attr() method:

element.style('cursor', null)

style() as getter

returns value (string, number, ...)

Similar to attr() the style() method can also act as a getter:

element.style('cursor')
// => pointer

Or even a full getter:

element.style()
// => 'cursor:pointer;fill:#f03;'

hide()

returns itself

Hide element:

element.hide()

show()

returns itself

Show (unhide) element:

element.show()

visible()

returns boolean

To check if the element is visible:

element.visible()

Class Names

addClass()

returns itself

Adds a given css class:

element.addClass('pink-flower')

classes()

returns array

Fetches the CSS classes for the node as an array:

element.classes()

hasClass()

returns boolean

Test the presence of a given css class:

element.hasClass('purple-rain')

removeClass()

returns itself

Removes a given css class:

element.removeClass('pink-flower')

toggleClass()

returns itself

Toggles a given css class:

element.toggleClass('pink-flower')

Data

The data() method allows you to bind arbitrary objects, strings and numbers to SVG elements.

data() as getter

returns value

Fetching the values is similar to the attr() method:

var key = rect.data('key')

data() as setter

returns itself

rect.data('key', { value: { data: 0.3 }})

Or set multiple values at once:

rect.data({
  forbidden: 'fruit'
, multiple: {
    values: 'in'
  , an: 'object'
  }
})

Removing the data altogether:

rect.data('key', null)

Your values will always be stored as JSON and in some cases this might not be desirable. If you want to store the value as-is, just pass true as the third argument:

rect.data('key', 'value', true)

Memory

remember() as getter

returns value

To retrieve a memory

rect.remember('oldBBox')

remember() as setter

returns itself

Storing data in-memory is very much like setting attributes:

rect.remember('oldBBox', rect.bbox())

Multiple values can also be remembered at once:

rect.remember({
  oldFill:    rect.attr('fill')
, oldStroke:  rect.attr('stroke')
})

forget()

returns itself

Erasing a single memory:

rect.forget('oldBBox')

Or erasing multiple memories at once:

rect.forget('oldFill', 'oldStroke')

And finally, just erasing the whole memory:

rect.forget()

Document Tree

add()

returns itself

Sets the calling element as the parent node of the argument. Returns the parent:

var rect = draw.rect(100, 100)
var group = draw.group()

group.add(rect) //-> returns group

addTo()

returns itself

Sets the calling element as a child node of the argument. Returns the child:

rect.addTo(group) //-> returns rect

clone()

returns SVG.Element

To make an exact copy of an element the clone() method comes in handy:

var clone = rect.clone()

This will create a new, unlinked copy. For making a linked clone, see the use element.
By default, the cloned element is placed directly after the original element.
When you pass a parent parameter to the clone() function it will append the cloned element to the given parent.

put()

returns SVG.Element

Sets the calling element as the parent node of the argument. Returns the child:

group.put(rect) //-> returns rect

putIn()

returns SVG.Element

Sets the calling element as a child node of the argument. Returns the parent:

rect.putIn(group) //-> returns group

remove()

returns itself

Removes the calling element from the svg document:

rect.remove()

replace()

returns SVG.Element

At the calling element's position in the svg document, replace the calling element with the element passed to the method.

rect.replace(draw.circle(100))

toDoc()

returns itself

Same as toParent() but with the root-node as parent

toParent()

returns itself

Moves an element to a different parent (similar to addTo), but without changing its visual representation. All transformations are merged and applied to the element.

rect.toParent(group) // looks the same as before

ungroup() / flatten()

returns itself

Break up a group/container and move all the elements to a given parent node without changing their visual representations. The result is a flat svg structure, e.g. for exporting.

Ungroup all elements in this group recursively and places them into the given parent

group.ungroup(parent, depth)
// (default: parent container of the calling element)

Call it on the whole document to get a flat svg structure:

drawing.ungroup()

Break up the group and places all elements in the drawing:

group.ungroup(drawing)

Break up all groups until it reaches a depth of 3:

drawing.ungroup(null, 3)

Flat and export svg:

var svgString = drawing.ungroup().svg()

Arranging

You can arrange elements within their parent SVG document using the following methods.

after()

returns itself

Insert an element after another:

// inserts circle after rect
rect.after(circle)

before()

returns itself

Insert an element before another:

// inserts circle before rect
rect.before(circle)

back()

returns itself

Move element to the back:

rect.back()

backward()

returns itself

Move element one step backward:

rect.backward()

front()

returns itself

Move element to the front:

rect.front()

forward()

returns itself

Move element one step forward:

rect.forward()

next()

returns SVG.Element

Get the next sibling:

rect.next()

position()

returns number

Get the position (a number) of rect between its siblings:

rect.position()

previous()

returns SVG.Element

Get the previous sibling:

rect.previous()

siblings()

returns array

The arrange.js module brings some additional methods. To get all siblings of rect, including rect itself:

rect.siblings()

Geometry

point()

returns SVG.Point

Transforms a point from screen coordinates to the elements coordinate system.

// e is some mouseevent
var point = path.point(e.screenX, e.screenY) // {x, y}

inside()

returns boolean

To check if a given point is inside the bounding box of an element you can use the inside() method:

var rect = draw.rect(100, 100).move(50, 50)

rect.inside(25, 30) //-> returns false
rect.inside(60, 70) //-> returns true

Note: the x and y positions are tested against the relative position of the element. Any offset on the parent element is not taken into account.