{"id":15998,"library":"cytoscape-fcose","title":"fCoSE Layout for Cytoscape.js","description":"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.","status":"active","version":"2.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/iVis-at-Bilkent/cytoscape.js-fcose","tags":["javascript","cytoscape","cytoscape-extension"],"install":[{"cmd":"npm install cytoscape-fcose","lang":"bash","label":"npm"},{"cmd":"yarn add cytoscape-fcose","lang":"bash","label":"yarn"},{"cmd":"pnpm add cytoscape-fcose","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; essential for the extension to function within a Cytoscape.js instance.","package":"cytoscape","optional":false},{"reason":"Runtime dependency providing the core CoSE algorithm logic.","package":"cose-base","optional":false},{"reason":"Optional runtime dependency used for advanced features like packing disconnected components.","package":"cytoscape-layout-utilities","optional":true}],"imports":[{"note":"The extension is typically imported as a default export and then registered with `cytoscape.use()`.","wrong":"import { fcose } from 'cytoscape-fcose';","symbol":"fcose","correct":"import fcose from 'cytoscape-fcose';\n// then register with cytoscape\ncy.use(fcose);"},{"note":"For CommonJS environments, `require()` is used to get the default export for registration.","wrong":"const { fcose } = require('cytoscape-fcose');","symbol":"fcose (CommonJS)","correct":"const fcose = require('cytoscape-fcose');\n// then register with cytoscape\ncy.use(fcose);"},{"note":"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.","symbol":"LayoutOptions type (TypeScript)","correct":"import cytoscape, { LayoutOptions } from 'cytoscape';\n// then use:\nconst options: LayoutOptions = { name: 'fcose', ... };"}],"quickstart":{"code":"import cytoscape from 'cytoscape';\nimport fcose from 'cytoscape-fcose';\n\ncytoscape.use(fcose);\n\nconst cy = cytoscape({\n  container: document.getElementById('cy'),\n  elements: [\n    { data: { id: 'a', parent: 'c' } },\n    { data: { id: 'b', parent: 'c' } },\n    { data: { id: 'c' } },\n    { data: { id: 'd' } },\n    { data: { id: 'e' } },\n    { data: { id: 'ab', source: 'a', target: 'b' } },\n    { data: { id: 'ad', source: 'a', target: 'd' } },\n    { data: { id: 'de', source: 'd', target: 'e' } }\n  ],\n  style: [\n    { selector: 'node', style: { 'background-color': '#666', label: 'data(id)' } },\n    { selector: '$node > node', style: { 'background-color': '#ccc', 'padding': '10px' } },\n    { selector: 'edge', style: { 'width': 3, 'line-color': '#ccc', 'target-arrow-color': '#ccc', 'target-arrow-shape': 'triangle', 'curve-style': 'bezier' } }\n  ]\n});\n\nconst layoutOptions = {\n  name: 'fcose',\n  animate: true,\n  animationDuration: 500,\n  // Constraints example: fix node 'd' at a position\n  fixedNodeConstraint: [{\n    nodeId: 'd',\n    position: { x: 300, y: 100 }\n  }],\n  // Alignment constraint example: align 'a' and 'b' vertically\n  alignmentConstraint: {\n    vertical: [['a', 'b']],\n    horizontal: []\n  },\n  nodeRepulsion: 4500,\n  idealEdgeLength: 50,\n  edgeElasticity: 0.45,\n  nestingFactor: 0.1,\n  numIter: 2500,\n  initialEnergyOnIncremental: 0.3 // For incremental layout\n};\n\ncy.layout(layoutOptions).run();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Consolidate your alignment constraint arrays to include all co-aligned nodes in a single sub-array, e.g., `vertical: [['node1', 'node2', 'node3']]`.","message":"When 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']]`.","severity":"gotcha","affected_versions":">=2.0.0"},{"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`.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `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.","severity":"deprecated","affected_versions":">=1.2.2"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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' })`.","cause":"The `fcose` layout extension has not been properly registered with your Cytoscape.js instance before attempting to use it.","error":"TypeError: Cannot read properties of undefined (reading '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.","cause":"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.","error":"Error: The layout 'fcose' is not registered."},{"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']]`.","cause":"Your `alignmentConstraint` configuration contains redundant or non-compact array definitions for nodes that should be aligned.","error":"Error: `alignmentConstraint` must be given in most compact form. Example: `['n1', 'n2', 'n3']` instead of `['n1', 'n2'], ['n1', 'n3']`."}],"ecosystem":"npm"}