A lightweight library for manipulating and animating SVG.

Svg.js has no dependencies and aims to be as small as possible. The base library is 3k gzipped, with all bells and whistles about 5k.

Svg.js is licensed under the terms of the MIT License.

See svgjs.com for an introduction, documentation and some action.

Use the svg() function to create a SVG document within a given html element:

var draw = svg('paper').size(300, 300)
var rect = draw.rect(100, 100).attr({ fill: '#f06' })

The first argument can either be an id of the element or the selected element itself. This will generate the following output:

<div id="paper">
	<svg xmlns="http://www.w3.org/2000/svg" version="1.1" xlink="http://www.w3.org/1999/xlink" width="300" height="300">
		<rect width="100" height="100" fill="#f06"></rect>
	</svg>
</div>

By default the svg canvas follows the dimensions of its parent, in this case #paper:

var draw = svg('paper').size('100%', '100%')

By default this library assumes the client's browser supports SVG. You can test support as follows:

if (SVG.supported) {
  var draw = svg('paper')
  var rect = draw.rect(100, 100)
} else {
  alert('SVG not supported')
}

The viewBox attribute of an <svg> element can be managed with the viewbox() method. When supplied with arguments it will act as a setter:

draw.viewbox(0, 0, 297, 210)

Without any attributes an instance of SVG.ViewBox will be returned:

var box = draw.viewbox()

But the best thing about the viewbox() method is that you can get the zoom of the viewbox:

var box = draw.viewbox()
var zoom = box.zoom

If the size of the viewbox equals the size of the svg canvas, the zoom value will be 1.

Rects have two arguments, their width and height:

var rect = draw.rect(100, 100)

Ellipses, like rects, have two arguments, their width and height:

var ellipse = draw.ellipse(100, 100)

The only argument necessary for a circle is the diameter:

var circle = draw.circle(100)

Note that this generates an <ellipse> element instead of a <circle>. This choice has been made to keep the size of the library down.

The line element always takes four arguments, x1, y1, x2 and y2:

var line = draw.line(0, 0, 100, 150)

The polyline element defines a set of connected straight line segments. Typically, polyline elements define open shapes:

// polyline('x,y x,y x,y')
var polyline = draw.polyline('10,20 30,40 50,60')

Polyline strings consist of a list of points separated by spaces: x,y x,y x,y.

The polygon element, unlike the polyline element, defines a closed shape consisting of a set of connected straight line segments:

// polygon('x,y x,y x,y')
var polygon = draw.polygon('10,20 30,40 50,60')

Polygon strings are exactly the same as polyline strings. There is no need to close the shape as the first and last point will be connected automatically.

The path string is similar to the polygon string but much more complex in order to support curves:

// path('path data')
var path = draw.path('M10,20L30,40')

For more details on path data strings, please refer to the SVG documentation: http://www.w3.org/TR/SVG/paths.html#PathData

When creating images the width and height values should be defined:

// image(src, width, height)
var image = draw.image('/path/to/image.jpg', 200, 200).move(100, 100)

The first argument of a text element is the actual text content:

var text = draw.text("svg\nto\nthe\npoint.").move(300, 0)

Changing text afterwards is also possible with the text() method:

text.text('Brilliant!')

To get the raw text content:

text.content

The sugar.js module provides some syntax sugar specifically for this element type:

text.font({
  family:   'Helvetica'
, size:     144
, anchor:   'middle'
, leading:  1.5
})

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

// get a single attribute
rect.attr('x')

// 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')

With the transform() method elements can be scaled, rotated, translated and skewed:

rect.transform({
  rotation: 45
, cx:       100
, cy:       100
})

All available transformations are:

rect.transform({
  x:        [translation on x-axis]
, y:        [translation on y-axis]
, rotation: [degrees]
, cx:       [x rotation point]
, cy:       [y rotation point]
, scaleX:   [scaling on x-axis]
, scaleX:   [scaling on y-axis]
, skewX:    [skewing on x-axis]
, skewY:    [skewing on y-axis]
})

Important: matrix transformations are not yet supported.

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

rect.move(200, 350);

Note that you can also use the following code to move elements around:

rect.attr({ x: 20, y: 60 })

Although move() is much more convenient because it will always use the upper left corner as the position reference, whereas with using attr() the x and y reference differ between element types. For example, rect uses the upper left corner with the x and y attributes, circle and ellipse use their center with the cx and cy attributes and thereby simply ignoring the x and y values you might assign.

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

rect.size(200, 300)

Same as with move() 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.

This is an extra method to move an element by its center:

rect.center(150, 150)

We all love to have a little hide:

rect.hide()

and show:

rect.show()

To check if the element is visible:

rect.visible()

Pretty straightforward:

rect.remove()

To remove all elements in the svg document:

draw.clear()

path.bbox()

This will return an instance of SVG.BBox containing the following values:

{ height: 20, width: 20, y: 20, x: 10, cx: 30, cy: 20 } 

As opposed to the native getBBox() method any translations used with the transform() method will be taken into account.

If you would iterate over all the children() of the svg document, you might notice also the <defs> and <g> elements will be included. To iterate the shapes only, you can use the each() method:

draw.each(function(i, children) {
  this.fill({ color: '#f06' })
})

Animating elements is very much the same as manipulating elements, the only difference is you have to include the animate() method:

rect.animate().move(150, 150)

The animate() method will take two arguments. The first is milliseconds, the second ease:

rect.animate(2000, '>').attr({ fill: '#f03' })

By default milliseconds will be set to 1000, ease will be set to <>. All available ease types are:

• <>: ease in and out
• >: ease out
• <: ease in
• -: linear
• a function

For the latter, here is an example of the default <> function:

function(pos) { return (-Math.cos(pos * Math.PI) / 2) + 0.5; }

For more easing equations, have a look at the svg.easing.js plugin.

Note that the animate() method will not return the targeted element but an instance of SVG.FX which will take the following methods:

Of course attr():

rect.animate().attr({ fill: '#f03' })

The move() method:

rect.animate().move(100, 100)

And the center() method:

rect.animate().center(200, 200)

If you include the sugar.js module, rotate() and skew() will be available as well:

rect.animate().rotate(45).skew(25, 0)

Animations can be stopped in two ways.

By calling the stop() method:

rect.animate().move(200, 200)

rect.stop()

Or by invoking another animation:

rect.animate().move(200, 200)

rect.animate().center(200, 200)

Finally, you can add callback methods using after():

rect.animate(3000).move(100, 100).after(function() {
  this.animate().attr({ fill: '#f06' })
})

This functionality requires the fx.js module which is included in the default distribution.

Fill and stroke are used quite often. Therefore two convenience methods are provided:

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

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

To set the overall opacity of an element:

rect.opacity(0.5)

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

// rotate(degrees)
rect.rotate(45)

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

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

This functionality requires the sugar.js module which is included in the default distribution.

The easiest way to mask is to use a single element:

var ellipse = draw.ellipse(80, 40).move(10, 10).fill({ color: '#fff' })

rect.maskWith(ellipse)

But you can also use multiple elements:

var ellipse = draw.ellipse(80, 40).move(10, 10).fill({ color: '#fff' })
var text = draw.text('SVG.JS').move(10, 10).font({ size: 36 }).fill({ color: '#fff' })

var mask = draw.mask().add(text).add(ellipse)

rect.maskWith(mask)

If you want the masked object to be rendered at 100% you need to set the fill color of the masking object to white. But you might also want to use a gradient:

var gradient = image.parent.gradient('linear', function(stop) {
  stop.at({ offset: 0, color: '#000' })
  stop.at({ offset: 100, color: '#fff' })
})

var ellipse = draw.ellipse(80, 40).move(10, 10).fill({ color: gradient.fill() })

rect.maskWith(ellipse)

For your convenience, the masking element is also referenced in the masked element. This would be useful in case you want to change, or remove the mask:

rect.mask.remove()

If you want to clip elements rather than masking them, have a look at the svg.clippath.js plugin.

This functionality requires the mask.js module which is included in the default distribution.

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

Move element to the front:

rect.front()

Move element to the back:

rect.back()

Note that back() will move the element to position 1, not 0, because the <defs> node is already located at position 0.

Move element one step forward:

rect.forward()

Move element one step backward:

rect.backward()

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

rect.siblings()

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

rect.position()

Get the next sibling:

rect.next()

Get the previous sibling:

rect.previous()

This functionality requires the arrange.js module which is included in the default distribution.

Grouping elements is useful if you want to transform a set of elements as if it were one. All element within a group maintain their position relative to the group they belong to. A group has all the same element methods as the root svg document:

var group = draw.group()
group.path('M10,20L30,40')

Existing elements from the svg document can also be added to a group:

group.add(rect)

This functionality requires the group.js module which is included in the default distribution.

With this feature you can nest svg documents within each other. Nested svg documents have exactly the same features as the main, top-level svg document:

var nested = draw.nested()

var rect = nested.rect(200, 200)

This functionality requires the nested.js module which is included in the default distribution.

There are linear and radial gradients. The linear gradient can be created like this:

var gradient = draw.gradient('linear', function(stop) {
  stop.at({ offset: 0, color: '#333', opacity: 1 })
  stop.at({ offset: 100, color: '#fff', opacity: 1 })
})

The offset and color parameters are required for stops, opacity is optional. Offset is an integer expressed in percentage. To define the direction you can set from x, y and to x, y:

gradient.from(0, 0).to(0, 100)

The from and to values are also expressed in percent. Finally, to use the gradient on an element:

rect.attr({ fill: gradient.fill() })

Radial gradients have a radius() method to define the outermost radius to where the inner color should develop:

var gradient = draw.gradient('radial', function(stop) {
  stop.at({ offset: 0, color: '#333', opacity: 1 })
  stop.at({ offset: 100, color: '#fff', opacity: 1 })
})

gradient.from(50, 50).to(50, 50).radius(50)

A gradient can also be updated afterwards:

gradient.update(function(stop) {
  stop.at({ offset: 10, color: '#333', opacity: 0.2 })
  stop.at({ offset: 90, color: '#f03', opacity: 1 })
})

And even a single stop can be updated:

var s1, s2, s3

draw.gradient('radial', function(stop) {
  s1 = stop.at({ offset: 0, color: '#000', opacity: 1 })
  s2 = stop.at({ offset: 50, color: '#f03', opacity: 1 })
  s3 = stop.at({ offset: 100, color: '#066', opacity: 1 })
})

s1.update({ offset: 10, color: '#0f0', opacity: 1 })

W3Schools has a great example page on how linear gradients and radial gradients work.

This functionality requires the gradient.js module which is included in the default distribution.

Patterns work very much like gradients, you only have to define the tile size:

var pattern = draw.pattern(20, 20, function(add) {
  add.rect(10, 10).fill('#000')
  add.rect(10, 10).move(10, 0).fill({ color: '#000', opacity: 0.5 })
  add.rect(10, 10).move(0, 10).fill({ color: '#000', opacity: 0.5 })
})

var circle = draw.circle(200, 200).fill(pattern.fill())

This will fill the circle with a checkered pattern. There is a lot more to patterns. Please refer to the Patterns section of the SVG specification.

This functionality requires the patterns.js module which is included in the default distribution.

Events can be bound to elements as follows:

rect.click(function() {
  this.fill({ color: '#f06' })
})

Removing it is quite as easy:

rect.click(null)

You can also bind event listeners to elements:

var click = function() {
  rect.fill({ color: '#f06' })
};

rect.on('click', click)

Note that the context of event listeners is not the same as events, which are applied directly to the element. Therefore this will not refer to the element when using event listeners.

Unbinding events is just as easy:

rect.off('click', click)

But there is more to event listeners. You can bind events to html elements as well:

SVG.on(window, 'click', click)

Obviously unbinding is practically the same:

SVG.off(window, 'click', click)

Available events are click, dblclick, mousedown, mouseup, mouseover, mouseout, mousemove, mouseenter, mouseleave, touchstart, touchend, touchmove and touchcancel.

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

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

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

rect.data('key')

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)

Svg.js has a modular structure. It is very easy to add you own methods at different levels. Let's say we want to add a method to all shape types then we would add our method to SVG.Shape:

SVG.extend(SVG.Shape, {
  paintRed: function() {
    return this.fill({ color: 'red' })
  }
})

Now all shapes will have the paintRed method available. Say we want to have the paintRed method on an ellipse apply a slightly different color:

SVG.extend(SVG.Ellipse, {
  paintRed: function() {
    return this.fill({ color: 'orangered' })
  }
})

The complete inheritance stack for SVG.Ellipse is:

SVG.Ellipse < SVG.Shape < SVG.Element

The SVG document can be extended by using:

SVG.extend(SVG.Doc, {
  paintAllPink: function() {
    var children = this.children()
    
    for (var i = 0, l = children.length; i < l; i++) {
      children[i].fill({ color: 'pink' })
    }
    
    return this
  }
})

Here are a few nice plugins that are available for svg.js:

• svg.shapes.js for more polygon based shapes.
• svg.easing.js for more easing methods on animations.
• svg.import.js import raw SVG data.
• svg.draggable.js to make elements draggable.
• svg.clippath.js clip elements.

Starting out with the default distribution of svg.js is good. Although you might want to remove some modules to keep the size at minimum.

You will need ruby, RubyGems, and rake installed on your system.

# dependencies:
$ ruby -v
$ gem -v
$ rake -V

# required to generate the minified version:
$ gem install uglifier

Build svg.js by running rake:

$ rake
Original version: 32.165k
Minified: 14.757k
Minified and gzipped: 4.413k, compression factor 7.289

The resulting files are:

1. dist/svg.js
2. dist/svg.min.js

To include optional modules and remove default ones, use the concat task. In this example, 'clip' is removed, but 'group' and 'arrange' are added:

$ rake concat[-clip:group:arrange] dist

To build the base library only including shapes:

rake concat[-fx:-event:-group:-arrange:-mask:-pattern:-gradient:-nested:-sugar] dist

The Rakefile has been borrowed from madrobby's Zepto

• Instance module
• Text on path module (write text along paths)

• Firefox 3+
• Chrome 4+
• Safari 3.2+
• Opera 9+
• IE9 +

• iOS Safari 3.2+
• Android Browser 3+
• Opera Mobile 10+
• Chrome for Android 18+
• Firefox for Android 15+

Visit the svg.js test page if you want to check compatibility with different browsers.

Important: this library is still in alpha, therefore the API might be subject to change in the course of development.