Elementobject

Element object

Description

The element object is used when specifying objects for creation, as in cy.add(). It is simply the fields of an element, specified as a plain object:

cy.add({
  data: { ... },
  position: { ... },
  renderedPosition: { ... }, // can be used as a shortcut to set rendered position but not for init options
                             // see the notes section for more info
  group: "nodes", // or "edges"
  bypass: { ... },
  selected: false, // or true
  locked: false, // or true
  grabbable: true, // or false
  selectable: true, // or false
  scratch: { ... }
});

Wherever an element object can be specified (e.g. to a function), a set of element objects can be passed. For example, an array of element objects suffices:

cy.add([

{ // 1st node
  data: { ... },
  group: "nodes"
},

{ // 2nd node
  data: { ... },
  group: "nodes"
}

]);

Alternatively, you can elide the group fields in each element object if the objects are put in a map by group:

cy.add({
  nodes: [
    { // 1st node
      data: { ... },
    },
    
    { // 2nd node
      data: { ... },
    } 
  ],
  
  edges: [ ... ]
});

Notes

Mandatory fields

For nodes, only the group field is mandatory, though it is strongly recommended to specify an initial position. Without an initial position specified, it is up to the renderer to position the node in an arbitrary place.

For edges, it is also necessary to specify data.target and data.source, since the source and target of an edge define it.

The data.id field is implicitly required. When elided, the data.id field will be given an arbitrary unique ID string.

Specifying rendered position instead of model position

It is important to note that the renderedPosition field is useful to set the on-screen position of nodes while adding them via cy.add().

Note that you can use the renderedPosition field only with cy.add() after the core has fired the ready event. You can not use the renderedPosition field in Cytoscape Web's initialisation options (i.e. in options.elements), because the renderer is not initialised yet and so can not be queried for rendered dimension calculations.

The only scenario where it makes sense to use the renderedPosition field is when you are adding nodes and would like to position them at a specific on-screen location. Otherwise, you should be using regular, model positions.