Registry / web-framework / cytoscape-fcose

cytoscape-fcose

library2.2.0jsnpmunverified

cytoscape-fcose is a high-performance layout extension for Cytoscape.js, implementing the fCoSE (fast Compound Spring Embedder) algorithm. Developed by the i-Vis Lab at Bilkent University, it is significantly faster than its predecessor, CoSE, offering up to 2x speed improvement while maintaining similar aesthetic quality for graph visualizations. The current stable version is 2.2.0, with releases occurring a few times a year, indicating active maintenance. A key differentiator is its robust support for compound graphs and an extensive set of user-defined constraints including fixed node positions, alignment (vertical/horizontal), and relative placement, which can also be applied incrementally. It achieves this by combining spectral layout techniques with force-directed methods, making it suitable for complex network visualizations where both speed and structural clarity are paramount.

web-framework

npm install cytoscape-fcose

github ↗package ↗

INSTALL

IMPORT

SIG · CYTOSCAPE-FCOSE

cytoscape-fcose

web-frameworkjavascriptv2.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

fcose

✓ import fcose from 'cytoscape-fcose'; // then register with cytoscape cy.use(fcose);

✗ import { fcose } from 'cytoscape-fcose';

The extension is typically imported as a default export and then registered with `cytoscape.use()`.

fcose (CommonJS)

✓ const fcose = require('cytoscape-fcose'); // then register with cytoscape cy.use(fcose);

✗ const { fcose } = require('cytoscape-fcose');

For CommonJS environments, `require()` is used to get the default export for registration.

LayoutOptions type (TypeScript)

✓ import cytoscape, { LayoutOptions } from 'cytoscape'; // then use: const options: LayoutOptions = { name: 'fcose', ... };

While `cytoscape-fcose` doesn't export its own specific types directly for layout options, you typically use `LayoutOptions` from `cytoscape` itself for type safety when configuring the layout.

This code initializes a Cytoscape.js instance, registers the `fcose` layout extension, defines a sample graph with compound nodes, and applies the fCoSE layout with animation and custom constraints for fixed node positions and alignment.

import cytoscape from 'cytoscape'; import fcose from 'cytoscape-fcose'; cytoscape.use(fcose); const cy = cytoscape({ container: document.getElementById('cy'), elements: [ { data: { id: 'a', parent: 'c' } }, { data: { id: 'b', parent: 'c' } }, { data: { id: 'c' } }, { data: { id: 'd' } }, { data: { id: 'e' } }, { data: { id: 'ab', source: 'a', target: 'b' } }, { data: { id: 'ad', source: 'a', target: 'd' } }, { data: { id: 'de', source: 'd', target: 'e' } } ], style: [ { selector: 'node', style: { 'background-color': '#666', label: 'data(id)' } }, { selector: '$node > node', style: { 'background-color': '#ccc', 'padding': '10px' } }, { selector: 'edge', style: { 'width': 3, 'line-color': '#ccc', 'target-arrow-color': '#ccc', 'target-arrow-shape': 'triangle', 'curve-style': 'bezier' } } ] }); const layoutOptions = { name: 'fcose', animate: true, animationDuration: 500, // Constraints example: fix node 'd' at a position fixedNodeConstraint: [{ nodeId: 'd', position: { x: 300, y: 100 } }], // Alignment constraint example: align 'a' and 'b' vertically alignmentConstraint: { vertical: [['a', 'b']], horizontal: [] }, nodeRepulsion: 4500, idealEdgeLength: 50, edgeElasticity: 0.45, nestingFactor: 0.1, numIter: 2500, initialEnergyOnIncremental: 0.3 // For incremental layout }; cy.layout(layoutOptions).run();

Debug

Known issues

breakingVersion 2.0.0 introduced significant new features including user-specified constraint support (fixed node, alignment, relative placement) and per-element values for options like `nodeRepulsion`, `edgeElasticity`, and `idealEdgeLength`. While existing configurations might still work, the structure of layout options for constraints is new and may require updating if attempting to use these advanced features.

fix

Review the fCoSE documentation for the new `fixedNodeConstraint`, `alignmentConstraint`, and `relativePlacementConstraint` options and update your layout configuration accordingly to leverage or properly handle these new features.

affects: >=2.0.0

gotchaWhen defining `alignmentConstraint`, arrays for vertical or horizontal alignment must be provided in the 'most compact form'. For instance, instead of `[['n1', 'n2'], ['n1', 'n3']]` for vertical alignment, use `[['n1', 'n2', 'n3']]`.

fix

Consolidate your alignment constraint arrays to include all co-aligned nodes in a single sub-array, e.g., `vertical: [['node1', 'node2', 'node3']]`.

affects: >=2.0.0

gotchaThe `cytoscape-fcose` extension has a peer dependency on `cytoscape` version `^3.2.0`. Using an incompatible major version of Cytoscape.js (e.g., Cytoscape.js v2.x or v4.x) may lead to runtime errors or unexpected layout behavior.

fix

Ensure your project's installed `cytoscape` version is compatible with `^3.2.0` (e.g., `npm install cytoscape@^3.2.0`). Check your `package.json` and `npm list cytoscape`.

affects: >=1.0.0

deprecatedThe `numeric.js` dependency was removed in v1.2.2, contributing to performance improvements. While not a direct breaking change for most users, it signifies internal refactoring.

fix

No direct action required for users; this was an internal dependency removal. Ensure you are on a recent version to benefit from performance improvements.

affects: >=1.2.2

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'layout')

The `fcose` layout extension has not been properly registered with your Cytoscape.js instance before attempting to use it.

fix

Ensure you call `cytoscape.use(fcose);` after importing the `cytoscape-fcose` module and before initializing any Cytoscape.js instances or calling `cy.layout({ name: 'fcose' })`.

Error: The layout 'fcose' is not registered.

The `fcose` layout extension module was imported but not correctly registered with Cytoscape.js, or the registration happened after an attempt to use the layout.

fix

Verify that `import fcose from 'cytoscape-fcose';` and `cytoscape.use(fcose);` are executed at an appropriate place in your application setup, typically at the entry point or before any graph initialization.

Error: `alignmentConstraint` must be given in most compact form. Example: `['n1', 'n2', 'n3']` instead of `['n1', 'n2'], ['n1', 'n3']`.

Your `alignmentConstraint` configuration contains redundant or non-compact array definitions for nodes that should be aligned.

fix

Refactor your `alignmentConstraint` to group all nodes that should be aligned in a single direction (vertical or horizontal) into one sub-array. For example, change `vertical: [['n1', 'n2'], ['n1', 'n3']]` to `vertical: [['n1', 'n2', 'n3']]`.

Upgrade

Version history

2.2.0latest on npm

Audit

Dependencies

cytoscaperequiredPeer dependency; essential for the extension to function within a Cytoscape.js instance.

cose-baserequiredRuntime dependency providing the core CoSE algorithm logic.

cytoscape-layout-utilitiesoptionalOptional runtime dependency used for advanced features like packing disconnected components.

Agent activity

22 hits · last 30 days

node

Resources

githubhttps://github.com/iVis-at-Bilkent/cytoscape.js-fcose ↗

packagehttps://www.npmjs.com/package/cytoscape-fcose ↗