or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-management.mdelement-collections.mdevent-system.mdextensions.mdgraph-algorithms.mdindex.mdlayout-system.mdstyling-system.md
tile.json

tessl/npm-cytoscape

Graph theory library for analysis and visualisation of network data with interactive rendering capabilities

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/cytoscape@3.33.x

To install, run

npx @tessl/cli install tessl/npm-cytoscape@3.33.0

index.mddocs/

Cytoscape.js

Cytoscape.js is a comprehensive graph theory library for analysis and visualization of network data. It provides a complete graph model, interactive renderer, and extensive collection of algorithms for building rich graph-based applications in browsers and Node.js environments.

Package Information

  • Package Name: cytoscape
  • Package Type: npm
  • Language: JavaScript (with TypeScript definitions)
  • Installation: npm install cytoscape

Core Imports

import cytoscape from "cytoscape";

For CommonJS:

const cytoscape = require("cytoscape");

Basic Usage

import cytoscape from "cytoscape";

// Create a cytoscape instance
const cy = cytoscape({
  container: document.getElementById("cy"), // container to render in
  elements: [
    // nodes
    { data: { id: "a" } },
    { data: { id: "b" } },
    // edges
    { data: { id: "ab", source: "a", target: "b" } },
  ],
  style: [
    {
      selector: "node",
      style: {
        "background-color": "#666",
        label: "data(id)",
      },
    },
    {
      selector: "edge",
      style: {
        width: 3,
        "line-color": "#ccc",
        "target-arrow-color": "#ccc",
        "target-arrow-shape": "triangle",
      },
    },
  ],
  layout: {
    name: "grid",
    rows: 1,
  },
});

// Add event listeners
cy.on("tap", "node", function (evt) {
  const node = evt.target;
  console.log("tapped " + node.id());
});

Architecture

Cytoscape.js is built around several key components:

  • Core Instance: The main cy object that manages the graph, viewport, and rendering
  • Element Collections: Fluent API for manipulating nodes and edges with chainable methods
  • Layout System: Pluggable layout algorithms for automatically positioning nodes
  • Event System: Comprehensive event handling for user interactions and graph changes
  • Styling System: CSS-like declarative styling with selectors and properties
  • Algorithm Library: Graph analysis algorithms for pathfinding, centrality, clustering, and more
  • Extension System: Plugin architecture for custom layouts, renderers, and functionality

Capabilities

Core Graph Management

Core functionality for creating cytoscape instances, managing graph data, and controlling the viewport. Essential for all cytoscape applications.

/**
 * Creates a new cytoscape instance
 * @param options - Configuration options for the instance
 * @returns Core cytoscape instance
 */
function cytoscape(options?: CytoscapeOptions): Core;

/**
 * Register an extension with cytoscape
 * @param type - Extension type ("core", "collection", "layout")
 * @param name - Extension name
 * @param extension - Extension implementation
 */
function cytoscape(type: string, name: string, extension: any): void;

interface CytoscapeOptions {
  container?: HTMLElement | null;
  elements?: ElementDefinition[];
  style?: StylesheetJson;
  layout?: LayoutOptions;
  data?: Record<string, any>;
  zoom?: number;
  pan?: Position;
  minZoom?: number;
  maxZoom?: number;
  zoomingEnabled?: boolean;
  panningEnabled?: boolean;
  boxSelectionEnabled?: boolean;
  selectionType?: "additive" | "single";
  // ... additional options
}

Core Management

Element Collections

Powerful collection-based API for selecting, manipulating, and querying nodes and edges. Supports method chaining and provides comprehensive graph traversal capabilities.

interface Collection {
  // Selection and filtering
  filter(selector: string): Collection;
  not(selector: string): Collection;
  eq(index: number): Collection;
  first(): Collection;
  last(): Collection;
  
  // Data manipulation
  data(key?: string, value?: any): any;
  removeData(keys?: string[]): Collection;
  id(): string;
  
  // Styling
  style(property?: string, value?: any): any;
  addClass(classes: string): Collection;
  removeClass(classes?: string): Collection;
  
  // Position and geometry
  position(pos?: Position): Position | Collection;
  boundingBox(): BoundingBox;
  
  // Events
  on(events: string, handler: EventHandler): Collection;
  off(events?: string, handler?: EventHandler): Collection;
  trigger(events: string, extraParams?: any[]): Collection;
}

Element Collections

Layout System

Comprehensive layout algorithms for automatic node positioning, from simple grids to complex force-directed layouts. Supports custom layouts and animation.

interface LayoutOptions {
  name: string;
  fit?: boolean;
  padding?: number;
  animate?: boolean;
  animationDuration?: number;
  ready?: () => void;
  stop?: () => void;
}

// Built-in layout types
interface GridLayoutOptions extends LayoutOptions {
  name: "grid";
  rows?: number;
  cols?: number;
}

interface CircleLayoutOptions extends LayoutOptions {
  name: "circle";
  radius?: number;
}

interface CoseLayoutOptions extends LayoutOptions {
  name: "cose";
  nodeRepulsion?: number;
  edgeElasticity?: number;
  gravity?: number;
}

Layout System

Graph Algorithms

Extensive collection of graph analysis algorithms including pathfinding, centrality measures, clustering, and connectivity analysis.

interface AlgorithmResult {
  // Search algorithms
  breadthFirstSearch(options: BfsOptions): BfsResult;
  depthFirstSearch(options: DfsOptions): DfsResult;
  dijkstra(options: DijkstraOptions): DijkstraResult;
  aStar(options: AStarOptions): AStarResult;
  
  // Centrality algorithms
  betweennessCentrality(options?: CentralityOptions): CentralityResult;
  closenessCentrality(options?: CentralityOptions): CentralityResult;
  pageRank(options?: PageRankOptions): PageRankResult;
  
  // Clustering algorithms
  markovClustering(options?: ClusteringOptions): ClusteringResult;
  kMeans(options: KMeansOptions): KMeansResult;
}

Graph Algorithms

Event System

Rich event system supporting user interactions, element lifecycle events, viewport changes, and custom events with delegation and namespacing.

interface EventHandler {
  (event: Event): void;
}

interface Event {
  target: Collection;
  type: string;
  position: Position;
  renderedPosition: Position;
  originalEvent?: MouseEvent | TouchEvent;
}

// Event types
type UserEvents = "tap" | "click" | "mousedown" | "mouseup" | "mouseover" | "mouseout";
type CollectionEvents = "add" | "remove" | "select" | "unselect" | "grab" | "drag" | "free";
type GraphEvents = "pan" | "zoom" | "viewport" | "layoutstart" | "layoutstop";

Event System

Styling and Appearance

CSS-like styling system with selectors, properties, and themes. Supports dynamic styling, animations, and complex visual customization.

interface StylesheetJson {
  selector: string;
  style: StyleProperties;
}

interface StyleProperties {
  // Node styles
  width?: number | string;
  height?: number | string;
  "background-color"?: string;
  "background-image"?: string;
  shape?: "ellipse" | "triangle" | "rectangle" | "diamond";
  label?: string;
  
  // Edge styles
  "line-color"?: string;
  "target-arrow-shape"?: "triangle" | "arrow" | "diamond";
  "curve-style"?: "straight" | "bezier" | "segments";
  
  // Text styles
  color?: string;
  "font-size"?: number | string;
  "text-valign"?: "top" | "center" | "bottom";
}

Styling System

Extensions and Plugins

Plugin architecture for extending cytoscape functionality with custom layouts, renderers, and utility functions.

// Extension registration
cytoscape.use(extension);

// Extension types
interface CoreExtension {
  (core: Core): void;
}

interface CollectionExtension {
  (collection: Collection): void;
}

interface LayoutExtension {
  name: string;
  run: (options: any) => void;
}

Extensions

Types

interface Position {
  x: number;
  y: number;
}

interface BoundingBox {
  x1: number;
  y1: number;
  x2: number;
  y2: number;
  w: number;
  h: number;
}

interface ElementDefinition {
  group?: "nodes" | "edges";
  data: NodeDataDefinition | EdgeDataDefinition;
  position?: Position;
  selected?: boolean;
  selectable?: boolean;
  locked?: boolean;
  grabbable?: boolean;
  classes?: string[];
  style?: StyleProperties;
}

interface NodeDataDefinition {
  id?: string;
  parent?: string;
  [key: string]: any;
}

interface EdgeDataDefinition {
  id?: string;
  source: string;
  target: string;
  [key: string]: any;
}