Skip to content

Traversing

Follow incidence, directed reachability, edge relations and connectivity.

#Traversal, layouts and algorithms

Collections can traverse edge incidence (source, target, connectedNodes, connectedEdges, outgoers, incomers and neighborhood), compound containment (parent, parents, children, descendants and siblings) and directed reachability (successors, predecessors, roots, leaves). Compound ancestry remains distinct from graph connectivity.

#Incidence and neighbourhood

#ele.source()

// The source node of the first edge
ele.source(): Collection<NodeData, EdgeData, NodeData>

The source node of the first edge.

Returns Collection<NodeData, EdgeData, NodeData>

the source node, or an empty collection for a non-edge

Example

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

Example graph and handle setup

#ele.target()

// The target node of the first edge
ele.target(): Collection<NodeData, EdgeData, NodeData>

The target node of the first edge.

Returns Collection<NodeData, EdgeData, NodeData>

the target node, or an empty collection for a non-edge

Example

console.log(cy.getElementById('ab').target().id()); // 'b'

Example graph and handle setup

#eles.sources()

// The source nodes of every edge in the collection, deduped
eles.sources(): Collection<NodeData, EdgeData, NodeData>

The source nodes of every edge in the collection, deduped.

Returns Collection<NodeData, EdgeData, NodeData>

the source nodes

Example

console.log(eles.sources().map(ele => ele.id())); // ["a","b"]

Example graph and handle setup

#eles.targets()

// The target nodes of every edge in the collection, deduped
eles.targets(): Collection<NodeData, EdgeData, NodeData>

The target nodes of every edge in the collection, deduped.

Returns Collection<NodeData, EdgeData, NodeData>

the target nodes

Example

console.log(eles.targets().map(ele => ele.id())); // ["b","c"]

Example graph and handle setup

#eles.connectedEdges(criterion?)

// Every edge incident on the nodes in this collection, deduped — answered off the CSR adjacency index, so it is O(incident edges) rather than a scan
eles.connectedEdges(criterion?: FilterLike<NodeData, EdgeData, EdgeData, NodeData | EdgeData>): Collection<NodeData, EdgeData, EdgeData>

Every edge incident on the nodes in this collection, deduped — answered off the CSR adjacency index, so it is O(incident edges) rather than a scan. Loops appear once.

Parameters
NameDescription
criterion: FilterLike<NodeData, EdgeData, EdgeData, NodeData | EdgeData>?

an optional query object or predicate to filter the result

Fields of criterion
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 incident edges

Example

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

Example graph and handle setup

#eles.connectedNodes(criterion?)

// The endpoint nodes of every edge in this collection, deduped
eles.connectedNodes(criterion?: FilterLike<NodeData, EdgeData, NodeData, NodeData | EdgeData>): Collection<NodeData, EdgeData, NodeData>

The endpoint nodes of every edge in this collection, deduped.

Parameters
NameDescription
criterion: FilterLike<NodeData, EdgeData, NodeData, NodeData | EdgeData>?

an optional query object or predicate to filter the result

Fields of criterion
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 endpoint nodes

Example

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

Example graph and handle setup

#eles.outgoers(criterion?)

// The immediate outgoing neighbourhood: the edges leaving these nodes plus the nodes they point at
eles.outgoers(criterion?: FilterLike<NodeData, EdgeData>): Collection<NodeData, EdgeData>

The immediate outgoing neighbourhood: the edges leaving these nodes plus the nodes they point at. One hop only — use successors() for the transitive closure.

Parameters
NameDescription
criterion: FilterLike<NodeData, EdgeData>?

an optional query object or predicate to filter the result

Fields of criterion
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 outgoing edges and their target nodes

Example

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

Example graph and handle setup

#eles.incomers(criterion?)

// The immediate incoming neighbourhood: the edges arriving at these nodes plus the nodes they come from
eles.incomers(criterion?: FilterLike<NodeData, EdgeData>): Collection<NodeData, EdgeData>

The immediate incoming neighbourhood: the edges arriving at these nodes plus the nodes they come from. One hop only — use predecessors() for the transitive closure.

Parameters
NameDescription
criterion: FilterLike<NodeData, EdgeData>?

an optional query object or predicate to filter the result

Fields of criterion
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 incoming edges and their source nodes

Example

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

Example graph and handle setup

#eles.neighborhood(criterion?)

// The open neighbourhood: the incident edges and the nodes on their far ends, ignoring edge direction, excluding the collection's own elements
eles.neighborhood(criterion?: FilterLike<NodeData, EdgeData>): Collection<NodeData, EdgeData>

The open neighbourhood: the incident edges and the nodes on their far ends, ignoring edge direction, excluding the collection's own elements.

Parameters
NameDescription
criterion: FilterLike<NodeData, EdgeData>?

an optional query object or predicate to filter the result

Fields of criterion
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 neighbouring edges and nodes

Example

console.log(eles.neighborhood().map(ele => ele.id())); // []

Example graph and handle setup

Also spelled eles.openNeighborhood.

See

Collection#closedNeighborhood to include these nodes

#eles.closedNeighborhood(criterion?)

// The open neighbourhood plus this collection's own nodes
eles.closedNeighborhood(criterion?: FilterLike<NodeData, EdgeData>): Collection<NodeData, EdgeData>

The open neighbourhood plus this collection's own nodes.

Parameters
NameDescription
criterion: FilterLike<NodeData, EdgeData>?

an optional query object or predicate to filter the result

Fields of criterion
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 closed neighbourhood

Example

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

Example graph and handle setup

#Directed reachability

#eles.roots(criterion?)

// Collection nodes with no non-loop incoming edge (whole-graph incidence)
eles.roots(criterion?: FilterLike<NodeData, EdgeData, NodeData, NodeData | EdgeData>): Collection<NodeData, EdgeData, NodeData>

Collection nodes with no non-loop incoming edge (whole-graph incidence).

Parameters
NameDescription
criterion: FilterLike<NodeData, EdgeData, NodeData, NodeData | EdgeData>?

an optional query object or predicate applied to the result, exactly as filter() takes it

Fields of criterion
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 source nodes

Example

console.log(eles.roots().map(ele => ele.id())); // ["a"]

Example graph and handle setup

#eles.leaves(criterion?)

// Collection nodes with no non-loop outgoing edge
eles.leaves(criterion?: FilterLike<NodeData, EdgeData, NodeData, NodeData | EdgeData>): Collection<NodeData, EdgeData, NodeData>

Collection nodes with no non-loop outgoing edge.

Parameters
NameDescription
criterion: FilterLike<NodeData, EdgeData, NodeData, NodeData | EdgeData>?

an optional query object or predicate applied to the result, exactly as filter() takes it

Fields of criterion
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 sink nodes

Example

console.log(eles.leaves().map(ele => ele.id())); // ["c"]

Example graph and handle setup

#eles.successors(criterion?)

// Everything reachable by following outgoing edges, transitively — the edges and nodes of the forward closure, excluding these nodes themselves (unless a cycle reaches them)
eles.successors(criterion?: FilterLike<NodeData, EdgeData>): Collection<NodeData, EdgeData>

Everything reachable by following outgoing edges, transitively — the edges and nodes of the forward closure, excluding these nodes themselves (unless a cycle reaches them).

Parameters
NameDescription
criterion: FilterLike<NodeData, EdgeData>?

an optional query object or predicate to filter the result

Fields of criterion
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 reachable edges and nodes

Example

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

Example graph and handle setup

#eles.predecessors(criterion?)

// Everything that reaches these nodes by following incoming edges, transitively
eles.predecessors(criterion?: FilterLike<NodeData, EdgeData>): Collection<NodeData, EdgeData>

Everything that reaches these nodes by following incoming edges, transitively.

Parameters
NameDescription
criterion: FilterLike<NodeData, EdgeData>?

an optional query object or predicate to filter the result

Fields of criterion
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 edges and nodes of the backward closure

Example

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

Example graph and handle setup

#Edge relations

#eles.edgesWith(others)

// The edges connecting this collection's nodes with others, in either direction
eles.edgesWith(others: Collection): Collection<NodeData, EdgeData, EdgeData>

The edges connecting this collection's nodes with others, in either direction.

Parameters
NameDescription
others: Collection

the nodes on the far side (a collection, never a selector string)

Returns Collection<NodeData, EdgeData, EdgeData>

the connecting edges

Example

const other = cy.getElementById('b');
console.log(cy.getElementById('a').edgesWith(other).map(ele => ele.id())); // ["ab"]

Example graph and handle setup

#eles.edgesTo(others)

// The edges running from this collection's nodes to others — edgesWith() restricted by direction
eles.edgesTo(others: Collection): Collection<NodeData, EdgeData, EdgeData>

The edges running from this collection's nodes to others — edgesWith() restricted by direction.

Parameters
NameDescription
others: Collection

the target-side nodes

Returns Collection<NodeData, EdgeData, EdgeData>

the directed connecting edges

Example

const other = cy.getElementById('b');
console.log(cy.getElementById('a').edgesTo(other).map(ele => ele.id())); // ["ab"]

Example graph and handle setup

#eles.parallelEdges(criterion?)

// The edges sharing endpoints with these edges, in either direction — including each edge itself
eles.parallelEdges(criterion?: FilterLike<NodeData, EdgeData, EdgeData, NodeData | EdgeData>): Collection<NodeData, EdgeData, EdgeData>

The edges sharing endpoints with these edges, in either direction — including each edge itself. These are the edges a bezier bundle fans apart.

Parameters
NameDescription
criterion: FilterLike<NodeData, EdgeData, EdgeData, NodeData | EdgeData>?

an optional query object or predicate to filter the result

Fields of criterion
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 parallel edges

Example

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

Example graph and handle setup

#eles.codirectedEdges(criterion?)

// The parallel edges pointing the same way — same source and same target — including each edge itself
eles.codirectedEdges(criterion?: FilterLike<NodeData, EdgeData, EdgeData, NodeData | EdgeData>): Collection<NodeData, EdgeData, EdgeData>

The parallel edges pointing the same way — same source and same target — including each edge itself.

Parameters
NameDescription
criterion: FilterLike<NodeData, EdgeData, EdgeData, NodeData | EdgeData>?

an optional query object or predicate to filter the result

Fields of criterion
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 codirected edges

Example

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

Example graph and handle setup

#Connected components

#eles.components(root?)

// Connected components within this collection (undirected), each as a collection of the reached nodes plus the collection's edges internal to that component
eles.components(root?: Collection | null): Collection<NodeData, EdgeData>[]

Connected components within this collection (undirected), each as a collection of the reached nodes plus the collection's edges internal to that component.

Parameters
NameDescription
root: Collection | null?

restricts the seed nodes; omit to seed from every node

Returns Collection<NodeData, EdgeData>[]

one collection per component

Example

console.log(eles.components().length); // 1

Example graph and handle setup

Also spelled eles.componentsOf.

#ele.component()

// The whole-graph connected component containing the first element
ele.component(): Collection<NodeData, EdgeData>

The whole-graph connected component containing the first element.

Returns Collection<NodeData, EdgeData>

the component as nodes and their connecting edges, computed over the whole graph rather than within this collection; an empty collection when this one is empty

Example

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

Example graph and handle setup

All guides · Alphabetical API index · Read continuously