SVG.js

Classes

SVG.js adds a lot of functionality that is not related to the SVG spec. Most of the extras are part of the OO nature but there are other useful utilities as well.


SVG.Box

The SVG.Box holds rectangular dimensions of an object. Available properties are:

  • x
  • y
  • width
  • height
  • x2
  • y2
  • cx
  • cy

merge()

returns itself

With merge(), two SVG.Box instances can be merged into one new instance, basically being the bounding box of the two original boxes. For example:

var box1 = draw.rect(100,100).move(50,50).bbox()
var box2 = draw.rect(100,100).move(200,200).bbox()
var box3 = box1.merge(box2)

transform()

returns SVG.Box

Transforms the box with a given matrix or transformation:

var transformedBox = box.transform(matrix)


SVG.List

inherits from native array

Lists are very useful if you want to modify or animate multiple elements at once. A list has access to all buildin array methods and will also accept all the same methods accessible on individual elements. Even methods introduced by your plugins are available! Every method returns a new List with the results of the method call. Therefore method chaining is possible if the called method supports it. On the other hand you can also retrieve a list of e.g. fills. Creating a list works exactly as you would expect:

// create some elements
var rect = draw.rect(100,100)
var circle = draw.circle(100).move(100,100).fill('#f09')

// create a set and add the elements
var list = new SVG.List([rect])
list.push(circle)

// list[0] == rect
// list[1] == circle

// change the fill of all elements in the set at once
list.fill('#ff0')

var allfilles = list.fill() // get all the colors

A single element can be a member of many sets. Sets also don't have a structural representation, in fact they are just fancy arrays.

animate()

returns SVG.List

Sets work with animations as well:

list.animate(3000).fill('#ff0')

each()

returns itself

Iterating over all members in a list using the spefified method or passed function:

list.each('fill', 'blue') // same as list.fill('blue')
list.each(function(item) {
  return item.fill('blue')
})


SVG.Array

SVG.Array inherits from a buildin array for supported platforms and from a fake array for non supporting platforms. It can hold anything but is especially useful for creating an array out of a number string delimited by a whitespace or comma:

'0.343 0.669 0.119 0 0 0.249 -0.626 0.13 0 0 0.172 0.334 0.111 0 0 0 0 0 1 0'

Can also be passed like this in a more manageable format:

new SVG.Array([ .343,  .669, .119, 0,   0
              , .249, -.626, .130, 0,   0
              , .172,  .334, .111, 0,   0
              , .000,  .000, .000, 1,  -0 ])

clone()

returns new instance

Makes a clone of the array and returns it:

var array = new SVG.Array()
var clone = array.clone()

Note: This method performs a deep clone on multi-dimensional arrays like SVG.PointArray and SVG.PathArray.
Note 2: Obviously, the returned array is of the same class as the cloned array (e.g. SVG.Array, SVG.PointArray or SVG.PathArray).

to()

returns itself

In order to animate array values the to() method lets you pass a destination value. This can be either the string value, a plain array or an instance of the same type of SVG.js array:

var array = new SVG.PointArray([[0, 0], [100, 100]])
array.to('100,0 0,100 200,200')

Make sure, that start and destination are of the same length

move()

returns itself

Moves geometry of the array with the given x and y values:

var array = new SVG.PointArray([[0, 0], [100, 100]])
array.move(33,75)
array.toString() //-> returns '33,75 133,175'

Note: this method is only available on SVG.PointArray and SVG.PathArray

reverse()

returns itself

Reverses the order of the array:

var array = new SVG.PointArray([[0, 0], [100, 100]])
array.reverse()
array.toString() //-> returns '100,100 0,0'

settle()

returns itself

When morphing is done the settle() method will eliminate any transitional points like duplicates:

array.settle()

size()

returns itself

Resizes geometry of the array by the given width and height values:

var array = new SVG.PointArray([[0, 0], [100, 100]])
array.move(100,100).size(222,333)
array.toString() //-> returns '100,100 322,433'

Note: this method is only available on SVG.PointArray and SVG.PathArray


SVG.PointArray

inherits from SVG.Array

Is a bit more complex and is used for polyline and polygon elements. This is a poly-point string:

'0,0 100,100'
// or
'0 0 100 100'
// or
'0, 0, 100, 100'

The flat array representation:

[0, 0, 100, 100]

The multi-dimensional array representation:

[
  [0, 0]
, [100, 100]
]

Precompiling it as an SVG.PointArray:

new SVG.PointArray([
  [0, 0]
, [100, 100]
])

Note that every instance of SVG.Polyline and SVG.Polygon carries a reference to the SVG.PointArray instance:

polygon.array() //-> returns the SVG.PointArray instance

bbox()

returns object

Gets the bounding box of the geometry of the array:

array.bbox()


SVG.PathArray

inherits from SVG.Array

Path arrays carry arrays representing every segment in a path string:

'M0 0L100 100z'

The flat array representation:

[ 'M', 0, 0, 'L', 100, 100, 'z' ]

The multi-dimensional array representation:

[
  ['M', 0, 0]
, ['L', 100, 100]
, ['z']
]

Precompiling it as an SVG.PathArray:

new SVG.PathArray([
  ['M', 0, 0]
, ['L', 100, 100]
, ['z']
])

Note that every instance of SVG.Path carries a reference to the SVG.PathArray instance:

path.array() //-> returns the SVG.PathArray instance

Syntax

The syntax for patharrays is very predictable. They are basically literal representations in the form of two dimentional arrays.

Move To

Original syntax is M0 0 or m0 0. The SVG.js syntax ['M',0,0] or ['m',0,0].

Line To

Original syntax is L100 100 or l100 100. The SVG.js syntax ['L',100,100] or ['l',100,100].

Horizontal line

Original syntax is H200 or h200. The SVG.js syntax ['H',200] or ['h',200].

Vertical line

Original syntax is V300 or v300. The SVG.js syntax ['V',300] or ['v',300].

Bezier curve

Original syntax is C20 20 40 20 50 10 or c20 20 40 20 50 10. The SVG.js syntax ['C',20,20,40,20,50,10] or ['c',20,20,40,20,50,10].

Or mirrored with S:

Original syntax is S40 20 50 10 or s40 20 50 10. The SVG.js syntax ['S',40,20,50,10] or ['s',40,20,50,10].

Or quadratic with Q:

Original syntax is Q20 20 50 10 or q20 20 50 10. The SVG.js syntax ['Q',20,20,50,10] or ['q',20,20,50,10].

Or a complete shortcut with T:

Original syntax is T50 10 or t50 10. The SVG.js syntax ['T',50,10] or ['t',50,10].

Arc

Original syntax is A 30 50 0 0 1 162 163 or a 30 50 0 0 1 162 163. The SVG.js syntax ['A',30,50,0,0,1,162,163] or ['a',30,50,0,0,1,162,163].

Close

Original syntax is Z or z. The SVG.js syntax ['Z'] or ['z'].

The best documentation on paths can be found at MDN.

bbox()

returns object

Gets the bounding box of the geometry of the array:

array.bbox()


SVG.Color

SVG.js has a dedicated color class handling different types of colors. Accepted values are:

  • hex string; three based (e.g. #f06) or six based (e.g. #ff0066) new SVG.Color('#f06')
  • rgb string; e.g. rgb(255, 0, 102) new SVG.Color('rgb(255, 0, 102)')
  • rgb object; e.g. { r: 255, g: 0, b: 102 } new SVG.Color({ r: 255, g: 0, b: 102 })
  • xyz object; e.g. { x: 255, y: 0, z: 102 } new SVG.Color({ x: 255, y: 0, z: 102 })
  • hsl object; e.g. { h: 255, s: 0, l: 102 } new SVG.Color({ h: 255, s: 0, l: 102 })
  • lab object; e.g. { l: 255, a: 0, b: 102 } new SVG.Color({ l: 255, a: 0, b: 102 })
  • lch object; e.g. { l: 255, c: 0, h: 102 } new SVG.Color({ l: 255, c: 0, h: 102 })
  • cmyk object; e.g. { c: 255, m: 0, y: 102, k:0 } new SVG.Color({ c: 255, m: 0, y: 102, k:0 })
  • parameterlist: new SVG.Color(255, 0, 102, 'rgb')

Note that when working with objects is important to provide all three values every time.

The SVG.Color instance has a few methods of its own.

To convert spaces into eachother the following methods are available:

color.rgb()
color.xyz()
color.hsl()
color.lab()
color.lch()
color.cmyk()

to()

returns SVG.Morphable

Get morphable color at given position:

var color = new SVG.Color('#ff0066').to('#000')
color.at(0.5).toHex() //-> '#7f0033'

toHex()

returns string

Get hex value:

color.toHex() //-> returns '#ff0066'

toRgb()

returns string

Get rgb string value:

color.toRgb() //-> returns 'rgb(255,0,102)'

SVG.Color.random()

With SVG.Color.random() a random color can be created. There a different modi available for color generation:

SVG.Color.random('vibrant') // this is the default
SVG.Color.random('sine')
SVG.Color.random('pastel')
SVG.Color.random('dark')
SVG.Color.random('rgb')
SVG.Color.random('lab')
SVG.Color.random('grey')


SVG.Matrix

Matrices in SVG.js have their own class SVG.Matrix. They add a lot of functionality like extracting transform values, matrix morphing and improvements on the native methods.

In SVG.js, matrices accept various values on initialization.

Without a value:

var matrix = new SVG.Matrix
matrix.toString() //-> returns matrix(1,0,0,1,0,0)

Six arguments:

var matrix = new SVG.Matrix(1, 0, 0, 1, 100, 150)
matrix.toString() //-> returns matrix(1,0,0,1,100,150)

A string value:

var matrix = new SVG.Matrix('1,0,0,1,100,150')
matrix.toString() //-> returns matrix(1,0,0,1,100,150)

An object value:

var matrix = new SVG.Matrix({ a: 1, b: 0, c: 0, d: 1, e: 100, f: 150 })
matrix.toString() //-> returns matrix(1,0,0,1,100,150)

Everyhing you can pass to the elements transform method can also be passed to the matrix constructor:

var matrix = new SVG.Matrix({ translate: [20, 20] })

A native SVGMatrix:

var svgMatrix = svgElement.getCTM()
var matrix = new SVG.Matrix(svgMatrix)
matrix.toString() //-> returns matrix(1,0,0,1,0,0)

Even an instance of SVG.Element:

var rect = draw.rect(50, 25)
var matrix = new SVG.Matrix(rect)
matrix.toString() //-> returns matrix(1,0,0,1,0,0)

transform()

Transforms the matrix with another matrix or transformation:

var matrix = new SVG.Matrix()
matrix.transform({rotate: 20})

decompose()

Decomposes the matrix into its affine parameters

var matrix = new SVG.Matrix()
matrix.decompose(cx, cy)

For the values returned, see (/manipulating/#transform)-getter

around()

returns SVG.Matrix

Performs a given matrix transformation around a given center point:

// cx, cy, matrix
matrix.around(100, 150, new SVG.Matrix().skew(0, 45))

The matrix passed as the third argument will be used to multiply.

to()

returns SVG.Morphable

This method will cretate a morpher which can be used to morph the matrix to a given position between 0 and 1:

matrix.to(matrix).at(0.27)

clone()

returns SVG.Matrix

Returns an exact copy of the matrix:

matrix.clone()

flip()

returns SVG.Matrix

Flips matrix over a given axis:

matrix.flip('x')

or

matrix.flip('y')

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

matrix.flip('x', 150)

or

matrix.flip('y', 100)

inverse()

returns SVG.Matrix

Creates an inverted matix:

matrix.inverse()

multiply()

returns SVG.Matrix

Multiplies by another given matrix:

matrix.matrix(matrix2)

rotate()

returns SVG.Matrix

Rotates matrix by degrees with one value given:

// degrees
matrix.rotate(45)

Rotates a matrix by degrees around a given point with three values:

// degrees, cx, cy
matrix.rotate(45, 100, 150)

scale()

returns SVG.Matrix

Scales matrix uniformal with one value:

// scale
matrix.scale(2)

Scales matrix non-uniformal with two values:

// scaleX, scaleY
matrix.scale(2, 3)

Scales matrix uniformal on a given center point with three values:

// scale, cx, cy
matrix.scale(2, 100, 150)

Scales matrix non-uniformal on a given center point with four values:

// scaleX, scaleY, cx, cy
matrix.scale(2, 3, 100, 150)

skew()

returns SVG.Matrix

Skews matrix a given degrees over x and or y axis with two values:

// degreesX, degreesY
matrix.skew(0, 45)

Skews matrix a given degrees over x and or y axis on a given point with four values:

// degreesX, degreesY, cx, cy
matrix.skew(0, 45, 150, 100)

toString()

returns string

Converts the matrix to a transform string:

matrix.toString()
// -> matrix(1,0,0,1,0,0)

translate()

returns SVG.Matrix

Translates matrix by a given x and y value:

matrix.translate(10, 20)


SVG.Number

Numbers in SVG.js have a dedicated number class to be able to process string values. Creating a new number is simple:

var number = new SVG.Number('78%')
number.plus('3%').toString() //-> returns '81%'
number.valueOf() //-> returns 0.81

Operators are defined as methods on the SVG.Number instance.

to()

returns SVG.Morphable

Get morphable number at given position:

var number = new SVG.Number('79%').to('3%')
number.at(0.55).toString() //-> '37.2%'

divide()

returns SVG.Number

Division:

number.divide('3%')

minus()

returns SVG.Number

Subtraction:

number.minus('3%')

plus()

returns SVG.Number

Addition:

number.plus('3%')

times()

returns SVG.Number

Multiplication:

number.times(2)

convert()

returns SVG.Number

Change number to another unit:

number.to('px')


SVG.Point

SVG.Point is returned by point() but is also a useful class to create vectors.

The contructor can take coordinates in many different forms:

var vector1 = new SVG.Point(1)
var vector2 = new SVG.Point(1,1)
var vector3 = new SVG.Point([1,1])
var vector4 = new SVG.Point({x:1,y:1})
var vector5 = new SVG.Point(new SVG.Point(1,1))

clone()

returns SVG.Point

Get a new SVG.Point with the same x/y value.

var newPoint = new SVG.Point(1,1).clone()

to()

returns SVG.Morphable

Get morphable object which can be used to get a point at a given position:

var point = new SVG.Point(1,1).to(11,10)
point.at(0.5) //-> {x: 6, y: 5.5}

transform()

returns SVG.Point

Transform point with matrix:

var point = new SVG.Point(1,1)
point.transform(new SVG.Matrix().skew(0, 45)) //-> {x: 1, y: 2}


SVG.EventTarget

This class is the class which all SVG Objects inherit from. It adds an event layer so that every object can have event functionality. How these methods work can be seen in the event-section

on()

Adds an event

off()

Removes an event

fire()

Fires an event

dispatch()

Fires an event and returns the event

Fork me on GitHub