Joint API

The 'curve' connector interpolates route points using a catmull-rom curve converted into cubic bezier curve. Tangents at endings of a curve can be defined using several options.

Available options:

The example of how to make the source point tangent always horizontal and target point tangent always go upwards:

link.connector('curve', {
    direction: curve.Directions.HORIZONTAL,
    targetDirection: curve.TangentDirections.UP
});

Available values for the direction option.

Available values for sourceDirection and targetDirection options.

The attributes in JointJS define how the graphics elements are to be rendered inside of the element and link views. All the standard SVG styling properties are available (both kebab-case and camelCase styles).

In addition JointJS modifies the behavior of existing attributes (the use of calc() for specifying attribute values) and defines new so-called "special" attributes and allows programmers to define their own.

calc()

The calc() function lets you perform calculations when specifying SVG attributes values.

Syntax:

The calc() function takes a simple expression as its parameter, with the expression's result used as the value. The expression can be any simple expression in one of the following forms:

• Variable

  'calc(w)'

• Variable Addition or Subtraction

  'calc(w + 5)'
  'calc(h - 10)'

• Multiplication Variable

  'calc(2 * w)'
  'calc(0.5 * h)'

• Multiplication Variable Addition or Subtraction

  'calc(2 * w + 5)'
  'calc(0.5 * h - 10)'

Where:

• Variable is a symbol representing a value that can change, when the model attributes change (size, attrs).

  variable	name	description
  w	width	The current width of the model (model.prop('size/width')). The value can be bound to an SVGElement's size instead by using ref attribute.
  h	height	The current height of the model (model.prop('size/height')). The value can be bound to an SVGElement's size instead by using ref attribute.
  x	x	The current x coordinate of the SVGElement in the element's coordinate system. If the attribute is not bound to a specific SVGElement with ref attribute, the value of x is always zero.
  y	y	The current y coordinate of the SVGElement in the element's coordinate system. If the attribute is not bound to a specific SVGElement with ref attribute, the value of y is always zero.
  s	shortest	The shortest side of the rectangle. The minimum of width and height.
  l	longest	The longest side of the rectangle. The maximum of width and height.
  d	diagonal	The length of the diagonal of the rectangle of size width and height.

• Multiplication is an optional floating number factor of the variable. It's a number followed by the * symbol.

  1.5 *

• Addition or Subtraction is an optional floating number added or subtracted from the variable. It's a + or - symbol followed by a number.

  + 5

Notes:

• Expression is case-sensitive.
• The +, - and * operators do not require whitespace.
• No extra parentheses are allowed.
• It is permitted to nest calc() functions, in which case the inner ones are evaluated first. e.g

  'M 0 0 H calc(w - calc(h))'

  .

It can be used with the following attributes:

• SVGRectElement
  • x
  • y
  • rx
  • ry
  • width
  • height
• SVGImageElement
  • x
  • y
  • width
  • height
• SVGLineElement
  • x1
  • x2
  • y2
  • y2
• SVGEllipseElement
  • cx
  • cy
  • rx
  • ry
• SVGCircleElement
  • cx
  • cy
  • r
• SVGPolygonElement
  • points
• SVGPolylineElement,
  • points
• SVGPathElement
  • d
• SVGTextElement
  • x
  • y
  • dx
  • dy
• Any SVG element (e.g. SVGGElement )
  • transform

Examples:

el.resize(200, 100); // dia.Element

// <rect joint-selector="myRect" width="200" height="100" rx="20" ry="10" />
el.attr('myRect', {
   width: 'calc(w)',
   height: 'calc(h)',
   rx: 'calc(0.1*w)',
   ry: 'calc(0.1*h)'
});

// <image joint-selector="myImage" x="105" y="55" />
el.attr('myImage/x', 'calc(0.5*w+5)');
el.attr('myImage/y', 'calc(0.5*h+5)');

// <path joint-selector="myPath" d="M 10 50 190 50" />
el.attr('myPath/d', 'M 10 calc(0.5*h) calc(w-10) calc(0.5*h)')

// <polygon joint-selector="myPolygon" points="0,0 200,0 200,100 0,100" />
el.attr('myPolygon/d', '0,0 calc(w),0 calc(w),calc(h) 0,calc(h)');

// Resize the rectangle to match the text size with extra 5 pixels of padding
// <rect joint-selector="myTextBackground" />
// <text joint-selector="myText" >Some text</text>
el.attr('myTextBackground', {
    ref: 'myText',
    x: 'calc(x - 5)',
    y: 'calc(y - 5)'
    width: 'calc(w + 10)',
    height: 'calc(h + 10)',
 });

Here is the list of all built-in attributes.

Move the subelement to the point at a given distance along the connection path but do not auto-orient it according to the path's gradient. Use a positive number to define the distance from the source of the link and a negative number from the target of the link. It is valid only within the LinkView context.

link.attr('rectSelector', { atConnectionLengthIgnoreGradient: 30, width: 10, height: 10, fill: 'red' });

alias: atConnectionLength

Move and auto-orient the subelement to the point at a given distance along the connection path. Use a positive number to define the distance from the source of the link and a negative number from the target of the link. It is valid only within the LinkView context.

link.attr('rectSelector', { atConnectionLength: 30, width: 10, height: 10, fill: 'red' });
link.attr('rectSelector', { atConnectionLengthKeepGradient: 30, width: 10, height: 10, fill: 'red' });

Move the subelement to the point at a given ratio of the connection total length but do not auto-orient it according to the path's gradient. It accepts a number in the [0,1] range. It is valid only within the LinkView context.

link.attr('rectSelector', { atConnectionRatioKeepGradient: .5, width: 10, height: 10, fill: 'red' });

alias: atConnectionRatio

Move and auto-orient the subelement to the point at a given ratio of the connection total length. It accepts a number in the [0,1] range. It is valid only within the LinkView context.

link.attr('rectSelector', { atConnectionRatio: .5, width: 10, height: 10, fill: 'red' });
link.attr('rectSelector', { atConnectionRatioKeepGradient: .5, width: 10, height: 10, fill: 'red' });

If true, set the shape of the subelement to match the shape of the LinkView (set the 'd' attribute to the result of the link connector). It's valid only for SVGPathElement within the LinkView context.

You can also provide an object with the following options:

link1.attr('pathSelector', { connection: true, stroke: 'red', fill: 'none' });
link2.attr('pathSelector', { connection: { stubs: -20 }});

Designate another subelement of the cell as a proxy target for the cell's container, whenever this subelement (the one on which this attribute is defined) becomes the target of an embedding. (Usually, this attribute needs to be defined on the `'root'` subelement of the cell, since that is the default target for the cell's container.) Expects a selector.

A change in the cell's container affects the following characteristics of the cell view:

• embedding highlighter

// `standard.Rectangle` has `root`, `body` and `label` subelements
const rect = new joint.shapes.standard.Rectangle();
// we want to have the `label` on the outside and under the `body` of the rectangle:
rect.attr(['label'], { refY: '100%', textVerticalAnchor: 'top' });
// normally, when a user tries to embed a child to the rectangle, the `root` subelement would be highlighted (the wrapper of `body` and `label`)
// however, we want only the `body` to be highlighted, so we need to specify it as a proxy for `root`:
rect.attr(['root', 'containerSelector'], 'body');

Valid only for <text> subelements.

If set to true, the SVGTextElement with empty content will be rendered. It's useful when the text needs to be editable.

The event attribute makes the selected node and its descendants trigger an arbitrary event when clicked (mousedown/touchstart). This event is triggered on the view itself and the paper. The paper handler is called with the signature cellView, evt, x, y, while the cell view handler is called only with evt, x, y.

element.attr({
  image: {
    // pointerdown on the image SVG node will trigger the `element:delete` event
    event: 'element:delete',
    xlinkHref: 'trash.png'
    width: 20,
    height: 20
  }
});
// Binding handler to the event
paper.on('element:delete', function(elementView, evt) {
  // Stop any further actions with the element view e.g. dragging
  evt.stopPropagation();
  if (confirm('Are you sure you want to delete this element?')) {
      elementView.model.remove();
  }
});

The fill attribute becomes a special attribute only in case it's defined as an object, instead of the usual SVG syntax (e.g. "#ffaabb"). If it's defined as an object, it is assumed to be either a gradient or pattern definition. It must have the form defined by the defineGradient() (resp. definePattern()) paper method.

Gradient

element.attr('rect/fill', {
    type: 'linearGradient',
    stops: [
        { offset: '0%', color: '#E67E22' },
        { offset: '20%', color: '#D35400' },
        { offset: '40%', color: '#E74C3C' },
        { offset: '60%', color: '#C0392B' },
        { offset: '80%', color: '#F39C12' }
    ]
});

Pattern

element.attr('rect/fill', {
    type: 'pattern',
    attrs: {
        width: 10,
        height: 10
    },
    markup: [{
        tagName: 'polygon',
        attributes: {
            points: '0,0 2,5 0,10 5,8 10,10 8,5 10,0 5,2'
        }
    }]
});

The filter attribute becomes a special attribute only in case it's defined as an object, instead of the usual SVG syntax (e.g. "url(#myfilter)"). If it's defined as an object, it must have the form defined by by the filterGradient() paper method.

element.attr('rect/filter', {
    name: 'dropShadow',
    args: {
        dx: 2,
        dy: 2,
        blur: 3
    }
});

Designate another subelement of the cell as a proxy target for the cell's magnet, whenever this subelement (the one on which this attribute is defined) becomes the source/target of a link. (Usually, this attribute needs to be defined on the `'root'` subelement of the cell, since that is the default target for the cell's magnet.) Expects a selector.

A change in the cell's magnet affects the following characteristics of the cell view:

• magnet highlight

It has no effect on the connection validation and link model attributes.

// `standard.Rectangle` has `root`, `body` and `label` subelements
const rect = new joint.shapes.standard.Rectangle();
// we want to have the `label` on the outside and under the `body` of the rectangle:
rect.attr(['label'], { refY: '100%', textVerticalAnchor: 'top' });
// normally, highlighters would appear around the `root` subelement (the wrapper of `body` and `label`)
// however, we want highlighters to highlight only to the `body` subelement, so we need to specify it as a proxy for `root`:
rect.attr(['root','highlighterSelector'], 'body');

When set to true, the subelement can become the source/target of a link during link reconnection. Useful for so called 'ports'. When set to magnet: 'passive', a new link won't be added to the graph when a user clicks on the respective magnet. This use case is common for the creation of 'input' ports.

const paper = new joint.dia.Paper({
    // Other Paper options
    // The default behaviour of magnet validation
    validateMagnet: function(_cellView, magnet, _evt) {
        return magnet.getAttribute('magnet') !== 'passive';
    }
});

const portIn = {
    label: {
        // Label position and markup
    },
    attrs: {
        portBody: {
            // Other portBody attributes
            magnet: 'passive' // No link added upon user click
        },
        label: { text: 'port' }
    },
    markup: [{
        tagName: 'rect',
        selector: 'portBody'
    }]
};

Designate another subelement of the cell as a proxy target for the cell's magnet, whenever this subelement (the one on which this attribute is defined) becomes the source/target of a link. (Usually, this attribute needs to be defined on the `'root'` subelement of the cell, since that is the default target for the cell's magnet.) Expects a selector.

A change in the cell's magnet affects the following characteristics of the cell view:

• link anchor
• link connection point
• connector
• router

It has no effect on the connection validation, magnet highlighter and the source and target link model attributes.

// `standard.Rectangle` has `root`, `body` and `label` subelements
const rect = new joint.shapes.standard.Rectangle();
// we want to have the `label` on the outside and under the `body` of the rectangle:
rect.attr(['label'], { refY: '100%', textVerticalAnchor: 'top' });
// normally, links would connect to the `root` subelement (the wrapper of `body` and `label`)
// however, we want links to connect only to the `body` subelement, so we need to specify it as a proxy for `root`:
rect.attr(['root','magnetSelector'], 'body');

An object containing at least an id property. This property uniquely identifies the port. If a link gets connected to a magnet that has also a port object defined, the id property of the port object will be copied to the port property of the source/target of the link.

Markup or CSS selector pointing to an element that is used as a reference for relative positioning attributes.

Set cx attribute of the subelement relatively to the width of the element referenced to by the selector in ref attribute. If the value is in the [0, 1] interval (or expressed in percentages, e.g. '80%'), the cx of the subelement will be set as a percentage of the width of the referenced element. If the value is <0 or >1, the height of the subelement will be smaller/bigger than the width of the referenced element by the amount specified. Note that this makes sense only for SVG elements that support rx and ry attributes, such as <ellipse>.

Set cy attribute of the subelement relatively to the height of the element referenced to by the selector in ref attribute. If the value is in the [0, 1] interval (or expressed in percentages, e.g. '80%'), the cy of the subelement will be set as a percentage of the height of the referenced element. If the value is <0 or >1, the height of the subelement will be smaller/bigger than the height of the referenced element by the amount specified. Note that this makes sense only for SVG elements that support rx and ry attributes, such as <ellipse>.

Set d attribute of the <path> subelement relatively to the dimensions and position of the element referenced by the selector in the ref attribute. The refD path data is scaled so that the path's dimensions match the reference element's dimensions, and translated so that the path's origin matches the origin of the reference element.

The original path data offset is preserved. This means that if the top-left corner of the refD bounding box does not lie at 0,0, the gap between the path and origin is preserved in the rendered shape, as well.

var Path = joint.dia.Element.define('examples.Path', {
    attrs: {
        path: {
            refDKeepOffset: 'M 10 10 30 10 30 30 z', // path offset is 10,10
            fill: 'red',
            stroke: 'black'
        }
    }
}, {
    markup: 'path'
});

var p = (new Path()).resize(40, 40).addTo(graph);
// the rendered path's `d` attribute will be 'M 10 10 50 10 50 50 z'
// can be obtained by `p.findView(paper).vel.findOne('path').attr('d');`

alias: refD

Set d attribute of the <path> subelement relatively to the dimensions and position of the element referenced by the selector in the ref attribute. The refD path data is scaled so that the path's dimensions match the reference element's dimensions, and translated so that the path's origin matches the origin of the reference element.

The original path data offset is not preserved. This means that if the top-left corner of the refD bounding box does not lie at 0,0, the path is translated so that this gap disappears. The rendered path then fits perfectly into the reference element's bounding box.

var Path = joint.dia.Element.define('examples.Path', {
    attrs: {
        path: {
            refDResetOffset: 'M 10 10 30 10 30 30 z', // path offset of 10,10 will be discarded
            fill: 'red',
            stroke: 'black'
        }
    }
}, {
    markup: 'path'
});

var p = (new Path()).resize(40, 40).addTo(graph);
// the rendered path's `d` attribute will be 'M 0 0 40 0 40 40 z'
// can be obtained by `p.findView(paper).vel.findOne('path').attr('d');`

alias: ref-dx

Make x-coordinate of the subelement relative to the right edge of the element referenced to by the selector in ref attribute.

Make y-coordinate of the subelement relative to the bottom edge of the element referenced to by the selector in ref attribute.

alias: ref-height

Set height of the subelement relatively to the height of the element referenced to by the selector in ref attribute. If the value is in the [0, 1] interval (or expressed in percentages, e.g. '80%'), the height of the subelement will be set as a percentage of the height of the referenced element. If the value is <0 or >1, the height of the subelement will be smaller/bigger than the height of the referenced element by the amount specified. Note that this makes sense only for SVG elements that support width and height attributes, such as <rect>.

Same as refHeight. Useful when one needs to resize an element absolutely and relatively at the same time. Note that all percentages are relative to 100% of the referenced height.

{ refHeight: 20, refHeight2: '-75%' } // resizes the element to 25% of the reference height (25% = 100% - 75%) plus extra 20 pixels

Set the points attribute of the <polygon> or <polyline> subelement relatively to the dimensions and position of the element referenced by the selector in the ref attribute. The refPoints are scaled so that the subelement's dimensions match the reference element's dimensions, and translated so that the their origin matches the origin of the reference element.

The original points offset is preserved. This means that if the top-left corner of the refPoints bounding box does not lie at 0,0, the gap between the points and origin is preserved in the rendered shape, as well.

var Polygon = joint.dia.Element.define('examples.Polygon', {
    attrs: {
        polygon: {
            refPoints: '10,10 30,10 30,30', // points offset is 10,10
            fill: 'red',
            stroke: 'black'
        }
    }
}, {
    markup: 'polygon'
});

var p = (new Polygon()).resize(40, 40).addTo(graph);
// the rendered polygon's `points` attribute will be '10,10 50,10 50,50'
// can be obtained by `p.findView(paper).vel.findOne('polygon').attr('points');`

alias: refPoints

Set the points attribute of the <polygon> or <polyline> subelement relatively to the dimensions and position of the element referenced by the selector in the ref attribute. The refPoints are scaled so that the subelement's dimensions match the reference element's dimensions, and translated so that the their origin matches the origin of the reference element.

The original points offset is not preserved. This means that if the top-left corner of the refPoints bounding box does not lie at 0,0, the subelement is translated so that this gap disappears. The rendered subelement then fits perfectly into the reference element's bounding box.

var Polygon = joint.dia.Element.define('examples.Polygon', {
    attrs: {
        polygon: {
            refPoints: '10,10 30,10 30,30', // points offset of 10,10 will be discarded
            fill: 'red',
            stroke: 'black'
        }
    }
}, {
    markup: 'polygon'
});

var p = (new Polygon()).resize(40, 40).addTo(graph);
// the rendered polygon's `points` attribute will be '0,0 40,0 40,40'
// can be obtained by `p.findView(paper).vel.findOne('polygon').attr('d');`

Set the r attribute of the subelement relatively to the circumscribed size (length of the diagonal of the bounding box) of the element referenced by the selector in the ref attribute. If the value is in the [0, 1] interval (or expressed in percentages, e.g. '80%'), the r of the subelement will be set as a percentage of the size of the referenced element. If the value is <0 or >1, the size of the subelement will be smaller/bigger than the size of the referenced element by the amount specified. Note that this makes sense only for SVG elements that support r attribute, such as <circle>.

alias: refR

Set the r attribute of the subelement relatively to the inscribed size (width or height of the bounding box, whichever is smaller) of the element referenced by the selector in the ref attribute. If the value is in the [0, 1] interval (or expressed in percentages, e.g. '80%'), the r of the subelement will be set as a percentage of the size of the referenced element. If the value is <0 or >1, the size of the subelement will be smaller/bigger than the size of the referenced element by the amount specified. Note that this makes sense only for SVG elements that support r attribute, such as <circle>.

Set rx attribute of the subelement relatively to the width of the element referenced to by the selector in ref attribute. If the value is in the [0, 1] interval (or expressed in percentages, e.g. '80%'), the rx of the subelement will be set as a percentage of the width of the referenced element. If the value is <0 or >1, the height of the subelement will be smaller/bigger than the width of the referenced element by the amount specified. Note that this makes sense only for SVG elements that support rx and ry attributes, such as <ellipse>.

Set ry attribute of the subelement relatively to the height of the element referenced to by the selector in ref attribute. If the value is in the [0, 1] interval (or expressed in percentages, e.g. '80%'), the ry of the subelement will be set as a percentage of the height of the referenced element. If the value is <0 or >1, the height of the subelement will be smaller/bigger than the height of the referenced element by the amount specified. Note that this makes sense only for SVG elements that support rx and ry attributes, such as <ellipse>.

alias: ref-width

Set width of the subelement relatively to the width of the element referenced to by the selector in ref attribute. If the value is in the [0, 1] interval (or expressed in percentages, e.g. '80%'), the width of the subelement will be set as a percentage of the width of the referenced element. If the value is <0 or >1, the width of the subelement will be smaller/bigger than the width of the referenced element by the amount specified. For example, 'ref-width': .75 sets the width of the subelement to 75% of the width of the referenced element. 'ref-width': 20 makes the width to be 20px less than the width of the referenced element. Note that this makes sense only for SVG elements that support width and height attributes, such as <rect>.

Same as refWidth. Useful when one needs to resize an element absolutely and relatively at the same time. Note that all percentages are relative to 100% of the referenced width.

{ refWidth: 20, refWidth2: '-75%' } // resizes the element to 25% of the reference width (25% = 100% - 75%) plus extra 20 pixels

alias: ref-x

Make x-coordinate of the subelement relative to the x-coordinate of the element referenced to by the selector in ref attribute. If ref-x is in the (0,1) interval (or expressed in percentages, e.g. '80%'), the offset is calculated from the fraction of the bounding box of the referenced element. Otherwise, it is an absolute value in pixels.

Same as refX. Useful when one needs to position an element absolutely and relatively at the same time.

{ refX: '50%', refX2: 20 } // moves the element by 50% of the referenced width plus extra 20 pixels.

alias: ref-y

Make y-coordinate of the subelement relative to the y-coordinate of the element referenced to by the selector in ref attribute. If ref-y is in the (0,1) interval (or expressed in percentages, e.g. '80%'), the offset is calculated from the fraction of the bounding box of the referenced element. Otherwise, it is an absolute value in pixels.

Same as refY. Useful when one needs to position an element absolutely and relatively at the same time.

{ refY: '50%', refY2: 20 } // moves the element by 50% of the referenced height plus extra 20 pixels.

If set to true, the subelement offset (the distance from x0 y0 to the most top-left point) will be reset to x0 y0.

element.attr({
  path: {
    // The path bbox for `d="M 10 10 20 20"` is x10 y10 w10 h10.
    d: 'M 10 10 20 20',
    // The path bbox will be changed to x0 y0 w10 h10.
    // This has same effect as passing path with `d="M 0 0 10 10"`
    resetOffset: true
  }
});

Valid for <path> subelements. It draws an SVG element at the beginning of a path (the source of the link). The element is automatically rotated based on the path direction. It must have the form defined by the defineMarker() paper method.

link.attr('line/sourceMarker', {
  type: 'circle', // SVG Circle
  fill: '#666',
  stroke: '#333',
  r: 5, // radius of the circle
  cx: 5 // move the centre of the circle 5 pixels from the end of the path
});

The stroke attribute becomes a special attribute only in case it's defined as an object. This has the exact same behaviour as the fill attribute.

An object containing CSS styles for a subelement.

Valid for <path> subelements. The same as sourceMarker but draws an SVG element at the end of the path. Note the coordinate system for drawing is rotated by 180 degrees for convenience (this allows to use the same marker for source and target and have them both face the connected elements).

Valid only for <text> subelements.

The text attribute contains the text that should be set on the subelement. If the provided string does not contain any newline characters ('\n'), the text is set directly as the content of the <text> subelement. Alternatively, if the provided string has multiple lines, each line becomes the content of a <tspan> child of the <text> subelement.

If you need the text to be automatically wrapped inside the <text> subelement, you should use the textWrap attribute instead. It can automatically add line breaks into the provided string as necessary, and mark them with newline characters.

Valid only for <text> subelements. textPath can be either a string or an object.

If it is a string, it specifies a path the text will be rendered along.

If it is an object, then it can contain a d property that specifies the path the text will be rendered along. Alternatively use selector property, which is useful for targeting a specific SVGPathElement within the shape. The option expects a string selector (CSS or JSONMarkup selector). Use startOffset property to control the text position on the path (e.g. '50%', 20). See the Vectorizer.text method for more details.

Valid only for <text/> subelements. The attribute is used to (top-, middle- or bottom-) align a text, relative to a point determined by reference to provided x, y, refX, refY, and similar attributes. See the Vectorizer.text method for more details.

Valid only for <text> subelements.

Similar to the text attribute, except the provided string is automatically wrapped to fit within the reference bounding box.

Expects an object with a text property and optional width and height, which can adjust the final size of the wrapped text. Negative values decrease the dimension (e.g. to add padding around the wrapped text); positive values increase the dimension. Percentage values are accepted as well.

If the text cannot fit into the bounding box as specified, the overflowing words are cut off. If the ellipsis option is provided, an ellipsis string is inserted before the cutoff. If no words can fit into the bounding box at all, no text is inserted. See util.breakText for more info.

textWrap: {
  text: 'lorem ipsum dolor sit amet consectetur adipiscing elit',
  width: -10, // reference width minus 10
  height: '50%', // half of the reference height
  ellipsis: true // could also be a custom string, e.g. '...!?'
}

Add the text-only description in form of a <title> element to the associated node. The title is not rendered as part of the graphics, but it's displayed as a tooltip.

element.attr('rect/title', 'Description of the rectangle');

Valid for <path> subelements. The same as sourceMarker but draws SVG elements at every vertex of the path.

alias: x-alignment

If set to 'middle', the subelement will be centered around its new x-coordinate.

alias: y-alignment

If set to 'middle', the subelement will be centered around its new y-coordinate.

The basic model for diagram cells. It's a Backbone model with a few additional properties and methods. Most importantly, every cell has a unique ID that is stored in the id property.

define(type [, defaultAttributes, prototypeProperties, staticProperties])

Helper to define a new Cell class or extend an existing one.

The type must be a unique identifier of the class, which determines the location of the class definition in the joint.shapes namespace (type is the path to the class definition delimited by dots: .). When creating an instance of the cell, attributes will be set to the value from the defaultAttributes, unless overridden by subclass or instance attributes.

// Define a new Ellipse class in `joint.shapes.examples` namespace
// Inherits from generic Element class
var Ellipse = joint.dia.Element.define('examples.Ellipse', {
    // default attributes
    markup: [{
        tagName: 'ellipse',
        selector: 'ellipse' // not necessary but faster
    ],
    attrs: {
        ellipse: {
            fill: 'white',
            stroke: 'black',
            strokeWidth: 4,
            refRx: .5,
            refRy: .5,
            refCx: .5,
            refCy: .5
        }
    }
});

// Instantiate an element
var ellipse = (new Ellipse()).position(100, 100).size(120, 50).addTo(graph);

// Define a new ColoredEllipse class
// Inherits from Ellipse
var ColoredEllipse = Ellipse.define('examples.ColoredEllipse', {
    // overridden Ellipse default attributes
    // other Ellipse attributes preserved
    attrs: {
        ellipse: {
            fill: 'lightgray'
        }
    }
}, {
    // prototype properties
    // accessible on `this.(...)` - as well as, more precisely, `this.prototype.(...)`
    // useful for custom methods that need access to this instance
    // shared by all instances of the class
    randomizeStrokeColor: function() {
        var randomColor = '#' + ('000000' + Math.floor(Math.random() * 16777215).toString(16)).slice(-6);
        return this.attr('ellipse/stroke', randomColor);
    }
}, {
    // static properties
    // accessible on `this.constructor.(...)`
    // useful for custom methods and constants that do not need an instance to operate
    // however, a new set of static properties is generated every time the constructor is called
    // (try to only use static properties if absolutely necessary)
    createRandom: function() {
        return (new ColoredEllipse()).randomizeStrokeColor();
    }
});

// Instantiate an element
var coloredEllipse = ColoredEllipse.createRandom().position(300, 100).size(120, 50).addTo(graph);

markup

Either an XML string or JSON markup specifying an array of JSON elements. Used as a template to build DOM Elements on the fly when the associated cellView is rendered.

XML String

A valid XML string that contains either a single tagName or XML that can be parsed with DOMParser.

markup: 'rect'
markup: '<rect class="rectangle"/>'
markup: '<rect><g><circle/><circle/></g>'

Note that defining Cell markup with XML strings is slower than defining it with JSON arrays, precisely because of the need for parsing. We strongly recommend you to use the JSON markup for your Cell definitions.

JSON Markup

JSON markup is defined recursively as an array of JSONElement, where JSONElement is a plain object with the following properties:

• tagName (string) (required) The type of element to be created.
• selector (string) A unique selector for targeting the element within the attr cell attribute.
• groupSelector (string | string[]) A selector for targeting multiple elements within the attr cell attribute. The group selector name must not be the same as an existing selector name.
• namespaceURI (string) The namespace URI of the element. It defaults to SVG namespace "http://www.w3.org/2000/svg".
• attributes (object with attributes name-value pairs) Attributes of the element.
• style (object with CSS property-value pairs) The style attribute of the element.
• className (string) The class attribute of the element.
• children (JSONMarkup) The children of the element.
• textContent (string) The text content of the element.

// single DOM element
markup: [{ tagName: 'rect' }]

// multiple DOM elements
markup: [{
    tagName: 'rect',
    selector: 'body'
}, {
    tagName: 'text',
    selector: 'label',
    attributes: {
        'stroke': 'none'
    }
}]

// nested DOM elements
markup: [{
    tagName: 'g',
    children: [{
        tagName: 'circle',
        selector: 'circle1',
        groupSelector: 'circles'
    }, {
        tagName: 'circle',
        selector: 'circle2',
        groupSelector: 'circles'
    }]
}]

JSON Markup attributes

Anything you define in markup is evaluated once at CellView creation (the DOM elements and their attributes). That means it's important to think about the runtime of your application. If you have SVG attributes that don't change throughout the runtime, you can add them to the markup.

As markup is something all instances of the element type are expected to have in common, inheriting from the subtype prototype is more efficient. Nevertheless, it is still possible to provide custom markup to individual instances of your class by providing markup later.

Anything in the attrs attribute is evaluated on every change of the model (e.g. a resize or an attrs change). As JointJS special attributes mostly depend on the current state of the model (size, attrs, angle), they should always be defined inside attrs.

SVG attributes that are modified at some point in the application should also be added to attrs (e.g. user changes the color of the element).

joint.dia.Element.define('standard.Rectangle', {
    attrs: {
        body: {
            width: 'calc(w)',
            height: 'calc(h)',
            stroke: 'red',
            fill: '#333333' // We wan't to modify the fill color of our instances
        },
        label: {
            // attributes
        }
    }
}, {
    markup: [{
        tagName: 'rect',
        selector: 'body',
        attributes: {
            'stroke-width': 2 // Use native SVG kebab-case for attributes in markup
        }
    }, {
        tagName: 'text',
        selector: 'label',
        attributes: {
            'stroke': 'none' // We don't need any instances to have a stroke value for text
        }
    }]
});

Setting attributes with selectors

• selector is unique i.e. can target a single node only.
• selector takes precedence over groupSelector.
• groupSelector targeting n nodes takes precedence over groupSelector targeting m nodes for n < m. When n === m the order how the attributes are applied is unspecified.

In the example below, the circle with the selector circle1 is filled with "red" color. All the other circles are filled with "blue" color.

cell.attr({
    circle1: { fill: 'red' },
    circles: { fill: 'blue', stroke: 'black' }
});

The view for the joint.dia.Cell model. It inherits from Backbone.View and is responsible for:

• Rendering a cell inside of a paper
• Handling the cell's pointer events
• Provides various methods for working with the cell (visually)

To find the view associated with a specific cell (model), use the findViewByModel method of the paper. For example:

var cellView = paper.findViewByModel(cell);

When you define a custom CellView, which listens to the underlying model changes and update itself (modifying its sub-elements directly) you should follow the instructions below in order to make the view work correctly in the async mode.

Note, that when a view needs an update (a model attribute has changed e.g. size has changed), it requests the update from the paper first. The paper confirms the update immediately (sync mode) or in the next animation frame (async mode). The updates may be also held by the paper as long as the paper is frozen and released when the paper changes its state to unfrozen.

The update requests are sent to the paper via flags and later received back all at once. The paper accumulates flags received and confirms the updates when the right time has come.

Methods and terminology

flagLabel - is an arbitrary string or array of strings

flags - are encoded flag labels

CellView.prototype.presentationAttributes - is an object that maps model attributes to flag labels.

CellView.prototype.confirmUpdate(flags, opt) - This method receives all scheduled flags and based on them updates the view

CellView.prototype.hasFlag(flags, flagLabel) - Checks whether a flagLabel is present in the current update.

CellView.addPresentationAttributes(presentationAttributes) - Extends the CellView presentation attributes with another presentationAttributes. - The method makes sure the original CellView attributes are preserved. It returns a new object with all presentation attributes.

Usage

const FadeView = joint.dia.ElementView.extend({
    // Make sure that all super class presentation attributes are preserved
    presentationAttributes: joint.dia.ElementView.addPresentationAttributes({
        // mapping the model attributes to flag labels
        faded: 'flag:opacity'
    }),
    confirmUpdate(flags, ...args) {
        joint.dia.ElementView.prototype.confirmUpdate.call(this, flags, ...args);
        if (this.hasFlag(flags, 'flag:opacity')) this.toggleFade();
    },
    toggleFade() {
        this.el.style.opacity = this.model.get('faded') ? 0.5 : 1;
    }
});

The basic model for diagram elements. It inherits from joint.dia.Cell with a few additional properties and methods specific to elements. For a quick introduction to elements, see our tutorial.

Elements' properties may be split into several groups according to their function:

Geometry

• position - coordinates of the element, provided as an object with x and y keys. The property may be accessed or set directly using regular Backbone set('position')/get('position') methods or through Element's translate() method.
• angle - angle of rotation of the element in degrees. The rotation origin is always the center of the element. The property may be accessed or set directly using regular Backbone set('angle')/get('angle') methods or through Element's rotate() method.
• size - size of the element, provided as an object with width and height keys. The property may be accessed or set directly using regular Backbone set('size')/get('size') methods or through Element's translate() method.

Presentation

Each joint.dia.Element defines its own SVG markup which is then used by joint.dia.ElementView to render the element to the paper. For instance, the joint.shapes.standard.Rectangle element (which inherits from joint.dia.Element) defines its markup using the JSON array notation as follows:

markup: [{
    tagName: 'rect',
    selector: 'body',
}, {
    tagName: 'text',
    selector: 'label'
}]

As we can see, the joint.shapes.standard.Rect shape consists of two subelements: one SVGRectElement named 'body' and one SVGTextElement named 'label'. The attrs object refers to the subelements' names (selectors) to provide SVG attributes to these constituent SVGElements.

Styling

The keys of the attrs object are selectors that match subelements defined in the element's markup. The values of this object are SVG attributes that will be set on the selected subelements. One can find the full list of SVG attributes and their descriptions online, e.g. on MDN.

For example, in order to set a red fill color on a subelement called 'body', the attrs object would contain:

body: { fill: 'red' }

If you simply need to change a value of an attribute, it is not recommended to modify the attrs object directly. Instead, use the element.attr() method.

We can use the joint.shapes.standard.Rectangle element (which inherits from joint.dia.Element) as an example. The attrs object in its definition is provided below:

attrs: {
    body: {
        refWidth: '100%',
        refHeight: '100%',
        strokeWidth: 2,
        stroke: '#000000',
        fill: '#FFFFFF'
    },
    label: {
        textVerticalAnchor: 'middle',
        textAnchor: 'middle',
        refX: '50%',
        refY: '50%',
        fontSize: 14,
        fill: '#333333'
    }
}

Notice that the object makes use of special JointJS attributes (e.g. refWidth, textVerticalAnchor) on top of standard SVG attributes (e.g. stroke, fill). All of these special attributes are listed in the attributes section of this documentation. You should also refer to our tutorial on special attributes.

Attributes

Attributes defined in markup are evaluated once at CellView creation, while attributes defined in attrs are evaluated on every model change. As JointJS special attributes usually depend on the current state of the model, we should define them in attrs, along with any other SVG attributes that will be modified in the runtime of your application.

Z

The z property specifies the stack order of the element in the SVG DOM. An element with a higher z value will be rendered in front of an element with a lower z value. (This also applies to Links.)

Ports

You may define and group ports on the Element with the ports attribute. Each can have its own markup and attrs, and its own label. Grouped ports may share properties and behaviors. See the element ports documentation for more information.

Nesting

The last two properties of elements are embeds and parent. These two are related to elements that contain or are contained within other elements, forming a hierarchical structure.

• embeds - a list of id's of the Cells that are embedded inside this Element.
• parent - the id of the Element that is the parent of this element. When a parent element is translated, all its children get translated too.

Events

Elements trigger several special events, detailed in the element events documentation.

Custom Element

It is possible to extend the joint.dia.Element class to create a custom element. A custom element may override Element properties to assign its own defaults. These values override builtin defaults, if provided, and are applied to all instances of the new Element type, unless an individual instance overrides them with its own values. The following Element properties are applicable in this context:

• markup - provide default element markup for all instances of this Element type, specified with a JSON array.
• attrs - provide default element styling for all instances of this Element type. These allow you to change the style and size of SVG elements, identified by their selectors.

Creating custom elements is explained in more detail in our tutorial.

The following list contains events that you can react on:

• change - generic event triggered for any change on the element - fn(element, opt)
• change:position - triggered when the element changes its position - fn(element, newPosition, opt)
• change:angle - triggered when the element gets rotated - fn(element, newAngle, opt)
• change:size - triggered when the element gets resized - fn(element, newSize, opt)
• change:attrs - triggered when the element changes its attributes - fn(element, newAttrs, opt)
• change:embeds - triggered when other cells were embedded into the element - fn(element, newEmbeds, opt)
• change:parent - triggered when the element got embedded into another element - fn(element, newParent, opt)
• change:z - triggered when the element is moved in the z-level (toFront and toBack) - fn(element, newZ, opt)
• transition:start - triggered when a transition starts. - fn(element, pathToAttribute)
• transition:end - triggered when a transiton ends. - fn(element, pathToAttribute)

// Listening for changes of the position to a single element
element1.on('change:position', function(element1, position) {
  alert('element1 moved to ' + position.x + ',' + position.y);
});
// All elements events are also propagated to the graph.
graph.on('change:position', function(element, position) {
  console.log('Element ' + element.id + 'moved to ' + position.x + ',' + position.y);
});
// Using the option parameter and a custom attribute
graph.on('change:custom', function(element, custom, opt) {
  if (opt.consoleOutput) {
    console.log('Custom attribute value changed to "' + custom + '"');
  }
});
element2.prop('custom', 'myValue', { consoleOutput: true });

Ports

Many diagramming applications deal with elements with ports. Ports are usually displayed as circles inside diagram elements and are used not only as "sticky" points for connected links, but they also further structure the linking information. It is common that certain elements have lists of input and output ports. A link might not then point to the element as a whole, but to a certain port instead.

It's easy to add ports to arbitrary shapes in JointJS. This can be done either by passing a ports definition as an option in the constructor, or using the ports API to get/add/remove single or multiple ports. For more information on how to define ports please see the Port configuration section.

Port API on joint.dia.Element

• hasPort / hasPorts
• addPort / addPorts
• removePort / removePorts
• getPort / getPorts
• portProp
• getPortsPositions

Port configuration

// Single port definition
const port = {
    // id: 'abc', // Generated if `id` value is not present
    group: 'a',
    args: {}, // Extra arguments for the port layout function, see `layout.Port` section
    label: {
        position: {
            name: 'left',
            args: { y: 6 } // Extra arguments for the label layout function, see `layout.PortLabel` section
        },
        markup: [{
            tagName: 'text',
            selector: 'label'
        }]
    },
    attrs: {
        body: { magnet: true, width: 16, height: 16, x: -8, y: -4, stroke: 'red', fill: 'gray'},
        label: { text: 'port', fill: 'blue' }
    },
    markup: [{
        tagName: 'rect',
        selector: 'body'
    }]
};

// a.) Add ports in constructor.
const rect = new joint.shapes.standard.Rectangle({
    position: { x: 50, y: 50 },
    size: { width: 90, height: 90 },
    ports: {
        groups: {
            'a': {}
        },
        items: [
            { group: 'a' },
            port
        ]
    }
});

// b.) Or add a single port using API
rect.addPort(port);

rect.getGroupPorts('a');
/*
   [
       { * Default port settings * },
       { * Follows port definition * },
       { * Follows port definition * }
    ]
*/

markup: [{
    tagName: 'g',
    children: [{
        tagName: 'rect',
        selector: 'bodyInner',
        className: 'outer',
        attributes: {
            'width': 15,
            'height': 15,
            'fill': 'red'
        }
    }, {
        tagName: 'rect',
        selector: 'bodyOuter',
        className: 'inner',
        attributes: {
            'width': 15,
            'height': 15,
            'fill': 'blue',
            'x': 10
        }
    }]
}]

{ position: 'left'}

// or ...
{
    position: {
        name: 'left',
        args: {
            dx: 10
        }
    }
}

markup: [{
    tagName: 'rect',
    selector: 'bodyMain',
    className: 'bodyMain'
}, {
    tagName: 'rect',
    selector: 'bodyInner',
    className: 'bodyInner'
}, {
    tagName: 'text',
    selector: 'label',
    className: 'label'
}]

<g model-id="...">
    <g class="joint-port"></g>         <!-- z: 0 -->
    <rect class="bodyMain"></rect>
    <g class="joint-port"></g>         <!-- z: 1 -->
    <rect class="bodyInner"></rect>
    <text class="label"></text>
    <g class="joint-port"></g>         <!-- z: 3 -->
    <g class="joint-port"></g>         <!-- z: auto -->
</g>

markup: [{
    tagName: 'g',
    selector: 'rotatable',
    className: 'rotatable',
    children: [{
        tagName: 'g',
        selector: 'scalable',
        className: 'scalable',
        children: [{
            tagName: 'rect',
            selector: 'bodyMain',
            className: 'bodyMain'
        }]
    }, {
        tagName: 'rect',
        selector: 'bodyInner',
        className: 'bodyInner'
    }, {
        tagName: 'text',
        selector: 'label',
        className: 'label'
    }]
}]

<g model-id="...">
    <g class="rotatable">
        <g class="joint-port"></g>         <!-- z: 0 -->
        <g class="scalable"><rect class="bodyMain"></rect></g>
        <g class="joint-port"></g>         <!-- z: 1 -->
        <rect class="bodyInner"></rect>
        <text class="label"></text>
        <g class="joint-port"></g>         <!-- z: 3 -->
        <g class="joint-port"></g>         <!-- z: auto -->
    </g>
</g>

All properties described above are optional, and everything has its own default. E.g. element.addPorts([{}, {}]) will add 2 ports with default settings.

Port groups configuration

While single port definitions are useful, what if we want more control over our ports? This is where a port group can come into play. A group allows us to define multiple ports with similar properties, and influence the default port alignment. Any individual port can override a property in a port group definition except the type of layout(E.g. position: 'left'). The group definition defines the layout, and the individual port args are the only way a port can affect it.

// Port definition for input ports group 
const portsIn = {
    position: {
        name: 'left', // Layout name
        args: {}, // Arguments for port layout function, properties depend on type of layout
    },
    label: {
        position: {
            name: 'left',
            args: { y: 6 }
        },
        markup: [{
            tagName: 'text',
            selector: 'label',
        }]
    },
    attrs: {
        body: { magnet: 'passive', width: 15, height: 15, stroke: 'red', x: -8, y: -8 },
        label: { text: 'in1', fill: 'black' }
    },
    markup: [{
        tagName: 'rect',
        selector: 'body'
    }]
};

// Define port groups in element constructor
const rect = new joint.shapes.basic.Rect({
    // ...
    ports: {
        groups: {
            'group1': portsIn,
            // 'group2': ...,
            // 'group3': ...,
        },
        items: [
             // Initialize 'rect' with port in group 'group1'
            {
                group: 'group1',
                args: { y: 40 } // Overrides `args` from the group level definition for first port 
            }
        ]
    }
});

// Add another port using Port API
rect.addPort(
    { group: 'group1', attrs: { label: { text: 'in2' }}}
);

markup: [{
    tagName: 'g',
    children: [{
        tagName: 'rect',
        selector: 'bodyInner',
        className: 'outer',
        attributes: {
            'width': 15,
            'height': 15,
            'fill': 'red'
        }
    }, {
        tagName: 'rect',
        selector: 'bodyOuter',
        className: 'inner',
        attributes: {
            'width': 15,
            'height': 15,
            'fill': 'blue',
            'x': 10
        }
    }]
}]

{ position: 'left'}

// or ...
{
    position: {
        name: 'left',
        args: {
            dx: 10
        }
    }
}

Custom markup

Both port and port label can have custom markup...

var rect = new joint.shapes.basic.Rect({
    // ...
});

rect.addPort({
    markup: [{
        tagName: 'rect', selector: 'body', attributes: { 'width': 20, 'height': 20, 'fill': 'blue' }
    }]
});

rect.addPort({
    markup: [{
        tagName: 'rect', selector: 'body', attributes: { 'width': 16, 'height': 16, 'fill': 'red' }
    }],
    label: {
        markup: [{ tagName: 'text', selector: 'label', attributes: { 'fill': '#000000' }}]
    },
    attrs: { label: { text: 'port' }}
});

...or, it can be set as an default port markup/port label markup on an element model:

var rect = new joint.shapes.basic.Rect({
    portMarkup: [{
        tagName: 'rect',
        selector: 'body',
        attributes: {
            'width': 20,
            'height': 20,
            'fill': 'blue',
            'stroke': 'black',
            'stroke-width': 5 // Use native SVG kebab-case for attributes in markup
        }
    }],
    portLabelMarkup: [{
        tagName: 'text',
        selector: 'label',
        attributes: {
            'fill': 'yellow'
        }
    }]
    // ...
});