# svg.js A lightweight library for manipulating and animating SVG. Svg.js has no dependencies and aims to be as small as possible. Svg.js is licensed under the terms of the MIT License. See [svgjs.com](http://svgjs.com) for an introduction, [documentation](http://documentup.com/wout/svg.js) and [some action](http://svgjs.com/test). [![Wout on Gittip](http://files.wout.co.uk/github/gittip.png)](https://www.gittip.com/wout/) ## Usage ### Create a SVG document Use the `SVG()` function to create a SVG document within a given html element: ```javascript var draw = SVG('drawing').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: ```html

``` By default the svg drawing follows the dimensions of its parent, in this case `#drawing`: ```javascript var draw = SVG('drawing').size('100%', '100%') ``` ### Checking for SVG support By default this library assumes the client's browser supports SVG. You can test support as follows: ```javascript if (SVG.supported) { var draw = SVG('drawing') var rect = draw.rect(100, 100) } else { alert('SVG not supported') } ``` ### SVG document Svg.js also works outside of the HTML DOM, inside an SVG document for example: ```xml ``` ### Sub pixel offset fix By default sub pixel offset won't be corrected. To enable it, call the `fixSubPixelOffset()` method: ```javascript var draw = SVG('drawing').fixSubPixelOffset() ``` ## Parent elements ### Main svg document The main svg.js initializer function creates a root svg node in the given element and retuns an instance of `SVG.Doc`: ```javascript var draw = SVG('drawing') ``` __`returns`: `SVG.Doc`__ _Javascript inheritance stack: `SVG.Doc` < `SVG.Container` < `SVG.Parent`_ ### Nested svg 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: ```javascript var nested = draw.nested() var rect = nested.rect(200, 200) ``` __`returns`: `SVG.Nested`__ _Javascript inheritance stack: `SVG.Nested` < `SVG.Container` < `SVG.Parent`_ ### Groups 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: ```javascript var group = draw.group() group.path('M10,20L30,40') ``` Existing elements from the svg document can also be added to a group: ```javascript group.add(rect) ``` __`returns`: `SVG.G`__ _Javascript inheritance stack: `SVG.G` < `SVG.Container` < `SVG.Parent`_ ### Hyperlink A hyperlink or `` tag creates a container that enables a link on all children: ```javascript var link = draw.link('http://svgjs.com') var rect = link.rect(100, 100) ``` The link url can be updated with the `to()` method: ```javascript link.to('http://apple.com') ``` Furthermore, the link element has a `show()` method to create the `xlink:show` attribute: ```javascript link.show('replace') ``` And the `target()` method to create the `target` attribute: ```javascript link.target('_blank') ``` Elements can also be linked the other way around with the `linkTo()` method: ```javascript rect.linkTo('http://svgjs.com') ``` Alternatively a block can be passed instead of a url for more options on the link element: ```javascript rect.linkTo(function(link) { link.to('http://svgjs.com').target('_blank') }) ``` __`returns`: `SVG.A`__ _Javascript inheritance stack: `SVG.A` < `SVG.Container` < `SVG.Parent`_ ### Defs The `` element is a container element for referenced elements. Elements that are descendants of a ‘defs’ are not rendered directly. The `` node lives in the main `element__ Even the main svg document: ```javascript var draw = SVG('drawing') draw.parent //-> returns the wrappig html element with id 'drawing' ``` __`returns`: node__ ### doc() For more specific parent filtering the `doc()` method can be used: ```javascript var draw = SVG('drawing') var rect = draw.rect(100, 100) rect.doc() //-> returns draw ``` Alternatively a class can be passed as the first argument: ```javascript var draw = SVG('drawing') var nested = draw.nested() var group = nested.group() var rect = group.rect(100, 100) rect.doc() //-> returns draw rect.doc(SVG.Doc) //-> returns draw rect.doc(SVG.Nested) //-> returns nested rect.doc(SVG.G) //-> returns group ``` __`returns`: element__ ## Child references ### first() To get the first child of a parent element: ```javascript draw.first() ``` __`returns`: element__ ### last() To get the last child of a parent element: ```javascript draw.last() ``` __`returns`: element__ ### children() An array of all children will can be retreives with the `children` method: ```javascript draw.children() ``` __`returns`: array__ ### each() The `each()` allows you to iterate over the all children of a parent element: ```javascript draw.each(function(i, children) { this.fill({ color: '#f06' }) }) ``` Deep traversing is also possible by passing true as the second argument: ```javascript // draw.each(block, deep) draw.each(function(i, children) { this.fill({ color: '#f06' }) }, true) ``` Note that `this` refers to the current child element. __`returns`: itself__ ### has() Checking the existence of an element within a parent: ```javascript var rect = draw.rect(100, 50) var group = draw.group() draw.has(rect) //-> returns true group.has(rect) //-> returns false ``` __`returns`: boolean__ ### index() Returns the index of given element and retuns -1 when it is not a child: ```javascript var rect = draw.rect(100, 50) var group = draw.group() draw.index(rect) //-> returns 0 group.index(rect) //-> returns -1 ``` __`returns`: number__ ### get() Get an element on a given position in the children array: ```javascript var rect = draw.rect(20, 30) var circle = draw.circle(50) draw.get(0) //-> returns rect draw.get(1) //-> returns circle ``` __`returns`: element__ ### clear() To remove all elements from a parent element: ```javascript draw.clear() ``` __`returns`: itself__ ## Manipulating elements ### attr() You can get and set an element's attributes directly using `attr()`. Get a single attribute: ```javascript rect.attr('x') ``` Set a single attribute: ```javascript rect.attr('x', 50) ``` Set multiple attributes at once: ```javascript rect.attr({ fill: '#f06' , 'fill-opacity': 0.5 , stroke: '#000' , 'stroke-width': 10 }) ``` Set an attribute with a namespace: ```javascript rect.attr('x', 50, 'http://www.w3.org/2000/svg') ``` Explicitly remove an attribute: ```javascript rect.attr('fill', null) ``` `getter`__`returns`: value__ `setter`__`returns`: itself__ ### transform() With the `transform()` method elements can be scaled, rotated, translated and skewed: ```javascript rect.transform({ rotation: 45 , cx: 100 , cy: 100 }) ``` You can also provide two arguments as property and value: ```javascript rect.transform('matrix', '1,0.5,0.5,1,0,0') ``` All available transformations are: ```javascript 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] , scaleY: [scaling on y-axis] , skewX: [skewing on x-axis] , skewY: [skewing on y-axis] , matrix: [a 6-digit matrix string; e.g. '1,0,0,1,0,0'] , a: [the first matrix digit] , b: [the second matrix digit] , c: [the third matrix digit] , d: [the fourth matrix digit] , e: [the fifth matrix digit] , f: [the sixth matrix digit] }) ``` Note that you can also apply transformations directly using the `attr()` method: ```javascript rect.attr('transform', 'matrix(1,0.5,0.5,1,0,0)') ``` Although that would mean you can't use the `transform()` method because it would overwrite any manually applied transformations. You should only go down this route if you know exactly what you are doing and you want to achieve an effect that is not achievable with the `transform()` method. `getter`__`returns`: number__ `setter`__`returns`: itself__ ### style() With the `style()` method the `style` attribute can be managed like attributes with `attr`: ```javascript rect.style('cursor', 'pointer') ``` Multiple styles can be set at once using an object: ```javascript rect.style({ cursor: 'pointer', fill: '#f03' }) ``` Or a css string: ```javascript rect.style('cursor:pointer;fill:#f03;') ``` Similarly to `attr()` the `style()` method can also act as a getter: ```javascript rect.style('cursor') // => pointer ``` Or even a full getter: ```javascript rect.style() // => 'cursor:pointer;fill:#f03;' ``` Explicitly deleting individual style definitions works the same as with the `attr()` method: ```javascript rect.style('cursor', null) ``` `getter`__`returns`: value__ `setter`__`returns`: itself__ ### move() Move the element to a given `x` and `y` position by its upper left corner: ```javascript rect.move(200, 350) ``` The `text` element has one optional argument: ```javascript // move(x, y, anchor) rect.move(200, 350, true) ``` The third argument can be used to move the text element by its anchor point rather than the calculated left top position. Note that you can also use the following code to move some elements (like images and rects) around: ```javascript 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. __`returns`: itself__ ### x() Move element only along x-axis by its upper left corner: ```javascript rect.x(200) ``` Without an argument the `x()` method serves as a getter as well: ```javascript rect.x() //-> returns 200 ``` `getter`__`returns`: value__ `setter`__`returns`: itself__ ### y() Move element only along y-axis by its upper left corner: ```javascript rect.y(350) ``` Without an argument the `y()` method serves as a getter as well: ```javascript rect.y() //-> returns 350 ``` `getter`__`returns`: value__ `setter`__`returns`: itself__ ### relative() The `move()`, `x()` and `y()` methods move an element to an absolute position. With the `relative()` method, elements can be moved relatively to their current position. This can be done by calling the `relative()` method before the `move()`, `x()` or `y()` methods in the method chain: ```javascript rect.move(100, 100).relative().move(20, -50) ``` This will set the `x` position of the element to `120` and the `y` position to `50`. It works the same way for `relative().x()` and `relative().y()`. __`returns`: object__ ### center() This is an extra method to move an element by its center: ```javascript rect.center(150, 150) ``` The `text` element has one optional argument: ```javascript // center(x, y, anchor) rect.center(150, 150, true) ``` The third argument can be used to center the text element by its anchor point rather than the calculated center position. __`returns`: itself__ ### cx() Move element only along x-axis by its center: ```javascript rect.cx(200) ``` Without an argument the `cx()` method serves as a getter as well: ```javascript rect.cx() //-> returns 200 ``` `getter`__`returns`: value__ `setter`__`returns`: itself__ ### cy() Move element only along y-axis by its center: ```javascript rect.cy(350) ``` Without an argument the `cy()` method serves as a getter as well: ```javascript rect.cy() //-> returns 350 ``` `getter`__`returns`: value__ `setter`__`returns`: itself__ ### size() Set the size of an element by a given `width` and `height`: ```javascript rect.size(200, 300) ``` Proporional resizing is also possible by leaving out `height`: ```javascript rect.size(200) ``` Or by passing `null` as the value for `width`: ```javascript rect.size(null, 200) ``` 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. __`returns`: itself__ ### width() Set only width of an element: ```javascript rect.width(200) ``` This method also acts as a getter: ```javascript rect.width() //-> returns 200 ``` `getter`__`returns`: value__ `setter`__`returns`: itself__ ### height() Set only height of an element: ```javascript rect.height(325) ``` This method also acts as a getter: ```javascript rect.height() //-> returns 325 ``` `getter`__`returns`: value__ `setter`__`returns`: itself__ ### hide() Hide element: ```javascript rect.hide() ``` __`returns`: itself__ ### show() Show element: ```javascript rect.show() ``` __`returns`: itself__ ### visible() To check if the element is visible: ```javascript rect.visible() ``` __`returns`: boolean__ ### clone() To make an exact copy of an element the `clone()` method comes in handy: ```javascript var clone = rect.clone() ``` __`returns`: element__ This will create an new, unlinked copy. If you want to make a linked clone have a look at the [use](#elements/use) element. ### remove() Pretty straightforward: ```javascript rect.remove() ``` __`returns`: itself__ ### replace() This method will replace the called element with the given element in the same position in the stack: ```javascript rect.replace(draw.circle(100)) ``` __`returns`: element__ ## Inserting elements ### add() Elements can be moved between parents via the `add()` method on any parent: ```javascript var rect = draw.rect(100, 100) var group = draw.group() group.add(rect) //-> returns group ``` __`returns`: itself__ ### put() Where the `add()` method returns the parent itself, the `put()` method returns the given element: ```javascript group.put(rect) //-> returns rect ``` __`returns`: element__ ### addTo() Similarly to the `add()` method on a parent element, elements have the `addTo()` method: ```javascript rect.addTo(group) //-> returns rect ``` __`returns`: itself__ ### putIn() Similarly to the `put()` method on a parent element, elements have the `putIn()` method: ```javascript rect.putIn(group) //-> returns group ``` __`returns`: element__ ## Geometry ### viewBox() The `viewBox` attribute of an `