Vectorizer API

JointJS exports three global variables, the joint namespace, the V variable and the g variable (that is described later in the Geometry section). The V variable is a function of a little SVG helper library that we call Vectorizer. The reason why this library sits in its own namespace and not inside the joint namespace is that it can be used completely standalone, even without JointJS. It is a very helpful library making life easier when dealing with SVG. You can think of it as of a very lightweight jQuery for SVG. If you want to use Vectorizer as a standalone library, see the download page that contains both the development and minified versions.



Return a Vectorizer object. If svg parameter is a string, construct SVG DOM elements from the string markup. If svg is an SVG DOM element, just wrap that element by the Vectorizer object and return it. You can think of this function as of the jQuery $ function except that the V function does not accept selectors. The Vectorizer object contains a reference to the original SVG DOM element in its node property.

var vel = V('<g><rect/><text/></g>');



Append className to the element class attribute if it doesn't contain it already. Return the Vectorizer object for easy chaining.


vel.animateAlongPath(attrs, path)

Animate the element along the path SVG element (or Vectorizer object). attrs contain Animation Timing attributes describing the animation. The following example shows how to send a token along a JointJS link element:

var c = V('circle', { r: 8, fill: 'red' });
c.animateAlongPath({ dur: '4s', repeatCount: 'indefinite' }, paper.findViewByModel(myLink).$('.connection')[0]);



Append another element (or elements) els as the last child of the element. els can be Vectorizer object(s) or SVG DOM element(s).


vel.attr(name, value)

Set SVG attribute with name and value on the element. If name is an object of the form { [name]: [value] }, more attributes will be set in one go.


vel.bbox([withoutTransformations, target])

Return the bounding box of the element after transformations are applied. If withoutTransformations is true, transformations of the element will not be considered when computing the bounding box. If target is specified, bounding box will be computed relatively to the target element.



Adds the given element (or elements) els before the Vectorizer element vel as a child of the parent node. els can be Vectorizer object(s) or SVG DOM element(s).



Clone the Vectorizer object creating a brand new copy of the element. This clone is not automatically added to the DOM.



Convert an SVG element to the SVG path element. It currently works for <path>, <line>, <polygon>, <polyline>, <ellipse>, <circle> and <rect>.



Convert an SVG element to the SVG path data (string of SVG path commands). It currently works for <path>, <line>, <polygon>, <polyline>, <ellipse>, <circle> and <rect>.



Return the Vectorizer object for the first <defs> element of the root SVG element. Note that the <defs> element is a good place to put referenced SVG elements like gradients, clip paths, filters and others.



Removes all the child nodes from the Vectorizer element.



Return all elements wrapped in the Vectorizer object matching the selector.


vel.findIntersection(ref, target)

Find the intersection of a line starting in the center of the SVG node ending in the point ref (an object of the form { x: Number, y: Number }). target is an SVG element to which this node's transformations are relative to. In JointJS, target is usually the paper.viewport SVG group element. Note that ref point must be in the coordinate system of the target for this function to work properly. This function returns a point in the target coordinte system (the same system as ref is in) if an intersection is found. Returns undefined otherwise.



Return the first element wrapped in the Vectorizer object matching the selector Return undefined if not such element was found.



Return true if the element contains className in its class attribute. Return false otherwise.



Return the index of the SVG element amongst its siblings.



Prepend another element (or elements) els as the first child of the element. els can be Vectorizer object(s) or SVG DOM element(s).



Remove the element from the DOM.



Remove className from the element class attribute if it contains it. Return the Vectorizer object for easy chaining.


vel.rotate(angle [, cx, cy])

Rotate the element by angle degrees. If the optional cx and cy coordinates are passed, they will be used as an origin for the rotation.



Sample the underlying SVG element (it currently works only on paths - where it is most useful anyway). Return an array of objects of the form { x: Number, y: Number, distance: Number }. Each of these objects represent a point on the path. This basically creates a discrete representation of the path (which is possible a curve). The sampling interval defines the accuracy of the sampling. In other words, we travel from the beginning of the path to the end by interval distance (on the path, not between the resulting points) and collect the discrete points on the path. This is very useful in many situations. For example, SVG does not provide a built-in mechanism to find intersections between two paths. Using sampling, we can just generate bunch of points for each of the path and find the closest ones from each set.


vel.scale(sx [, sy])

Scale the element by sx and sy factors. If sy is not passed, it will be considered the same as sx.



Return the Vectorizer object for the root SVG element of the element.


vel.text(content [, opt])

Set the text content of the element. This only makes sense for the <text> element. This method can deal with multi-line text in case the content string contains the new line characters (\n). opt.lineHeight can be optionally used to set the line height of the text. It defaults to '1em'. The opt.lineHeight can also be set to 'auto' in which case it is left on Vectorizer to set the best possible line height. This is useful if you annotate the text making it a rich-text (see below) and you don't want to set the line height to a fixed value for all the lines. opt.textPath can be either string or an object. If it is a string, it specifies a path the text should go along. If it is an object, then it should contain a d property that specifies the path the text should go along and optinally other attributes that will be set on the automatically created <textPath> SVG element such as startOffset.

t.text('my text\neven multiline')
t.text('my text\nwith custom line height', { lineHeight: '2em' })
t.text('text that goes along a path', { textPath: 'M 0 100 Q 30 10 100 0' })
t.text('another text that goes along a path', { textPath: { d: 'M 0 100 Q 30 10 100 0', startOffset: 50 } })

If opt.annotations array is set, the text will be annotated by the attributes defined in the annotations array. This means that you can easily render a rich-text. Each annotation in the annotations array is an object of the form { start: Number, end: Number, attrs: Object } where start (inclusive) and end (exclusive) define the range of the text content where the attrs SVG Attributes will be applied. If there are overlapping annotations, they will be smartly merged (classes concatenated, attributes merged, style can be always defined either as a string or an object).

var text = V('text', { x: 250, y: 150, fill: 'black' });
text.text('This is a rich text.\nThis text goes to multiple lines.', { lineHeight: 'auto', annotations: [
{ start: 5, end: 10, attrs: { fill: 'red', 'font-size': 30, rotate: '20' } },
{ start: 7, end: 15, attrs: { fill: 'blue' } },
{ start: 20, end: 30, attrs: { fill: 'blue', 'class': 'text-link', style: 'text-decoration: underline' } }

If opt.includeAnnotationIndices is set to true, each <tspan> will contain the 'annotations' attribute with comma separated indices of annotations that applied to that piece of text. Vectorizer provides some useful functions for working with annotations. Those are V.findAnnotationsAtIndex(), V.findAnnotationsBetweenIndexes() V.shiftAnnotations() and V.annotateString().


vel.toggleClass(className, switch)

Add or remove className from the element class attribute depending on either the class's presence or the value of the switch argument.


vel.toLocalPoint(x, y)

Convert a global point with coordinates x and y into the coordinate space of the element.


vel.transform([matrix], [opt])

When matrix is not provided, returns the current transformation matrix of the Vectorizer element.

When matrix is provided, applies the provided transformation matrix to the Vectorizer element.

You can clear previous transformations by passing opt with property absolute:true


vel.translate(tx [, ty])

Translate the element by tx pixels in x axis and ty pixels in y axis. ty is optional in which case the translation in y axis is considered zero.


vel.translateAndAutoOrient(position, reference, target)

Auto-orient the element. This basically implements the orient=auto attribute of markers. The easiest way of understanding on what this does is to imagine the element is an arrowhead. Calling this method on the arrowhead makes it point to the position point while being auto-oriented (properly rotated) towards the reference point. target is the element relative to which the transformations are applied. Usually the root SVG element which is also default if not target is passed.



Translate the element so that its new center will be at point p. p is an object of the form { x: [number], y: [number] }.



Return the SVG transformation matrix initialized with the matrix extension. extension is an object of the form: { a: [number], b: [number], c: [number], d: [number], e: [number], f: [number]}.


V.createSVGPoint(x, y)

Return the SVG point object initialized with the x and y coordinates.



Returns a SVG transform object.



Decompose the SVG transformation matrix into separate transformations. Return an object of the form: { translateX: [number], translateY: [number], scaleX: [number], scaleY: [number], skewX: [number], skewY: [number], rotation: [number] }.


V.findAnnotationsAtIndex(annotations, index)

Find all the annotations (see v.text()) that apply to the character at index.


V.findAnnotationsBetweenIndexes(annotations, start, end)

Find all the annotations (see v.text()) that apply to all the characters in the start and end range.



Return true if object is a vectorizer element.



Convert a rectangle r to SVG path commands. r is an object of the form { x: [number], y: [number], width: [number], height: [number], top-ry: [number], top-ry: [number], bottom-rx: [number], bottom-ry: [number] } where x, y, width, height are the usual rectangle attributes and [top-/bottom-]rx/ry allows for specifying radius of the rectangle for all its sides (as opposed to the built-in SVG rectangle that has only rx and ry attributes).


V.shiftAnnotations(annotations, index, offset)

Shift all the annotations (see v.text()) after character at index by offset positions.


V.transformPoint(p, matrix)

Transform a point specified by p (an object with x and y coordinates) by an SVG transformation represented by matrix. This is a convenient shortcut to calling:

var p = mySVGDocument.createSVGPoint();
p.x = x;
p.y = y;


V.transformRect(r, matrix)

Transform a rectangle specified by r (an object with x, y, width and height properties) by an SVG transformation represented by matrix. This function is used internally in the V.prototype.bbox method to return a bounding box of an SVG element relative to another SVG parent element. However, this can be used elsewhere too, that's why it is publicly exposed. Whenever you need to transform a bounding box to a coordinate system of another element, use this function. To get the transformation matrix of the target element relative to which you want to tranform your rectangle, use e.g. the native SVG method: var matrix = svgSourceElement.getTransformToElement(svgTargetElement).