Skip to content

Accessing elements

Look up elements by identity, region, query object or predicate.

#cy.collection()

// Create an empty collection bound to this core
cy.collection(): Collection<NodeData, EdgeData>

Create an empty collection bound to this core. Use it as an accumulator, for example cy.collection().union(cy.nodes({ selected: true })).

This method takes no arguments. Query with cy.elements(query) or build a collection with union() to include existing elements.

Returns Collection<NodeData, EdgeData>

a collection of zero elements

Example

console.log(cy.collection().map(ele => ele.id())); // []

Example graph and handle setup

Throws

if called with any argument — use cy.add() to insert definitions or set operations to build collections

#cy.getElementById(id)

// Look up one element by id through the O(1) id index
cy.getElementById(id: string): Collection<NodeData, EdgeData>

Look up one element by id through the O(1) id index.

Parameters
NameDescription
id: string

the element id

Returns Collection<NodeData, EdgeData>

a collection of one element, or an empty collection when no element has that id

Example

console.log(cy.getElementById('a').id()); // 'a'

Example graph and handle setup

Also spelled cy.$id, cy.byId.

#cy.elements(query?)

// Get all nodes and edges, or only those matching a query
cy.elements(query?: FilterLike<NodeData, EdgeData>): Collection<NodeData, EdgeData>

Get all nodes and edges, or only those matching a query. Nodes appear first, in insertion order, followed by edges.

Pass a query object such as { selected: true, data: { score: { gt: 2 } } } or a predicate such as ele => ele.data('score') > 2. Unknown query keys and selector strings throw.

Collections preserve their membership while reading current element values. Query again to include newly matching elements. Calls without a query return the same collection object until an element is added or removed.

Parameters
NameDescription
query: FilterLike<NodeData, EdgeData>?

a query object or an ( ele) => boolean predicate; omit for everything

Fields of query
NameDescription
group: GroupName?

restrict to one group

selected: boolean?

require the element (not) to be selected

selectable: boolean?

whether the element may be selected by the user

locked: boolean?

whether the element is locked in place

grabbed: boolean?

whether the user is dragging the element

grabbable: boolean?

whether the element may be dragged

active: boolean?

whether the element is under an active press

hovered: boolean?

whether the pointer is over the element

emphasized: boolean?

whether the element is in the current emphasis (* cy.emphasize())

parent: boolean?

structural (nodes only): has at least one child

childless: boolean?

structural (nodes only): has no children — exactly { parent: false }

child: boolean?

structural (nodes only): has a parent

orphan: boolean?

structural (nodes only): has no parent — exactly { child: false }

collapsed: boolean?

whether this compound parent is in collapsed miniature state (nodes only)

data: QueryData<Data>?

data-sidecar conditions per key; a bare value means equality. Typed, the keys are the queried elements' fields.

Returns Collection<NodeData, EdgeData>

the matching elements

Example

console.log(cy.elements().map(ele => ele.id())); // ["a","b","c","ab","bc"]

Example graph and handle setup

#cy.nodes(query?)

// The graph's nodes, optionally filtered
cy.nodes(query?: FilterLike<NodeData, EdgeData, NodeData>): Collection<NodeData, EdgeData, NodeData>

The graph's nodes, optionally filtered. Same query forms as elements(), restricted to the node group — and, with no query, the same cached collection behaviour.

Parameters
NameDescription
query: FilterLike<NodeData, EdgeData, NodeData>?

a query object or an ( ele) => boolean predicate

Fields of query
NameDescription
group: GroupName?

restrict to one group

selected: boolean?

require the element (not) to be selected

selectable: boolean?

whether the element may be selected by the user

locked: boolean?

whether the element is locked in place

grabbed: boolean?

whether the user is dragging the element

grabbable: boolean?

whether the element may be dragged

active: boolean?

whether the element is under an active press

hovered: boolean?

whether the pointer is over the element

emphasized: boolean?

whether the element is in the current emphasis (* cy.emphasize())

parent: boolean?

structural (nodes only): has at least one child

childless: boolean?

structural (nodes only): has no children — exactly { parent: false }

child: boolean?

structural (nodes only): has a parent

orphan: boolean?

structural (nodes only): has no parent — exactly { child: false }

collapsed: boolean?

whether this compound parent is in collapsed miniature state (nodes only)

data: QueryData<Data>?

data-sidecar conditions per key; a bare value means equality. Typed, the keys are the queried elements' fields.

Returns Collection<NodeData, EdgeData, NodeData>

the matching nodes

Example

console.log(cy.nodes().map(ele => ele.id())); // ["a","b","c"]

Example graph and handle setup

#cy.edges(query?)

// The graph's edges, optionally filtered
cy.edges(query?: FilterLike<NodeData, EdgeData, EdgeData>): Collection<NodeData, EdgeData, EdgeData>

The graph's edges, optionally filtered. Same query forms as elements(), restricted to the edge group — and, with no query, the same cached collection behaviour.

Parameters
NameDescription
query: FilterLike<NodeData, EdgeData, EdgeData>?

a query object or an ( ele) => boolean predicate

Fields of query
NameDescription
group: GroupName?

restrict to one group

selected: boolean?

require the element (not) to be selected

selectable: boolean?

whether the element may be selected by the user

locked: boolean?

whether the element is locked in place

grabbed: boolean?

whether the user is dragging the element

grabbable: boolean?

whether the element may be dragged

active: boolean?

whether the element is under an active press

hovered: boolean?

whether the pointer is over the element

emphasized: boolean?

whether the element is in the current emphasis (* cy.emphasize())

parent: boolean?

structural (nodes only): has at least one child

childless: boolean?

structural (nodes only): has no children — exactly { parent: false }

child: boolean?

structural (nodes only): has a parent

orphan: boolean?

structural (nodes only): has no parent — exactly { child: false }

collapsed: boolean?

whether this compound parent is in collapsed miniature state (nodes only)

data: QueryData<Data>?

data-sidecar conditions per key; a bare value means equality. Typed, the keys are the queried elements' fields.

Returns Collection<NodeData, EdgeData, EdgeData>

the matching edges

Example

console.log(cy.edges().map(ele => ele.id())); // ["ab","bc"]

Example graph and handle setup

#cy.filter(query)

// Filter the whole graph
cy.filter(query: FilterLike<NodeData, EdgeData>): Collection<NodeData, EdgeData>

Filter the whole graph. Identical to elements( query), kept for symmetry with eles.filter().

Parameters
NameDescription
query: FilterLike<NodeData, EdgeData>

a query object or an ( ele) => boolean predicate

Fields of query
NameDescription
group: GroupName?

restrict to one group

selected: boolean?

require the element (not) to be selected

selectable: boolean?

whether the element may be selected by the user

locked: boolean?

whether the element is locked in place

grabbed: boolean?

whether the user is dragging the element

grabbable: boolean?

whether the element may be dragged

active: boolean?

whether the element is under an active press

hovered: boolean?

whether the pointer is over the element

emphasized: boolean?

whether the element is in the current emphasis (* cy.emphasize())

parent: boolean?

structural (nodes only): has at least one child

childless: boolean?

structural (nodes only): has no children — exactly { parent: false }

child: boolean?

structural (nodes only): has a parent

orphan: boolean?

structural (nodes only): has no parent — exactly { child: false }

collapsed: boolean?

whether this compound parent is in collapsed miniature state (nodes only)

data: QueryData<Data>?

data-sidecar conditions per key; a bare value means equality. Typed, the keys are the queried elements' fields.

Returns Collection<NodeData, EdgeData>

the matching elements

Example

console.log(cy.filter(ele => ele.isNode()).length); // 3

Example graph and handle setup

Also spelled cy.$.

#cy.elementsInBox(x1, y1, x2, y2)

// Live, visible elements contained in the model-coordinate box (corners in any order): the box-selection query, answered by one columnar scan
cy.elementsInBox(x1: number, y1: number, x2: number, y2: number): Collection<NodeData, EdgeData>

Live, visible elements contained in the model-coordinate box (corners in any order): the box-selection query, answered by one columnar scan. Nodes count when their bounding box lies fully inside; edges when both endpoint node centers do (straight-edge endpoints are taken at the node centers).

boxSelectionMode does not reach here: this stays the pure geometric containment query whatever the gesture is set to. For the overlap question, boxSelectionMode( 'overlap') and drag a box, or test intersection yourself against eles.boundingBox(). (boxSelectionIncludesLabels is the one interaction setting that does reach here: with it on, a node's label box must be contained too.)

Parameters
NameDescription
x1: number

one corner's model x

y1: number

that corner's model y

x2: number

the opposite corner's model x

y2: number

that corner's model y

Returns Collection<NodeData, EdgeData>

the contained elements

Example

console.log(cy.elementsInBox(-50, -50, 50, 50).length); // 2

Example graph and handle setup

All guides · Alphabetical API index · Read continuously