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:
xywidthheightx2y2cxcy
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 colorsA 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 instancebbox()
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 instanceSyntax
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.81Operators 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