{"id":15997,"library":"cytoscape-cose-bilkent","title":"CoSE-Bilkent Layout for Cytoscape.js","description":"Cytoscape-cose-bilkent provides an advanced Compound Spring Embedder (CoSE) layout algorithm for the Cytoscape.js graph visualization library. Developed by the i-Vis Lab at Bilkent University, it is specifically designed to handle complex compound graphs with nested structures and supports non-uniform node dimensions, which is a key differentiator from simpler layout algorithms. The current stable version is 4.1.0. The package has seen performance improvements (e.g., v3.0.0) and architectural changes (v4.1.0) for better modularity. It maintains an active release cadence, primarily focusing on compatibility with Cytoscape.js and continuous improvements to its layout quality and speed. Its primary purpose is to produce aesthetically pleasing and readable layouts for graphs, particularly those with hierarchical or grouped components, by intelligently managing node repulsion, edge elasticity, and gravitational forces.","status":"active","version":"4.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/cytoscape/cytoscape.js-cose-bilkent","tags":["javascript","cytoscape","cytoscape-extension"],"install":[{"cmd":"npm install cytoscape-cose-bilkent","lang":"bash","label":"npm"},{"cmd":"yarn add cytoscape-cose-bilkent","lang":"bash","label":"yarn"},{"cmd":"pnpm add cytoscape-cose-bilkent","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; this is a Cytoscape.js extension and requires a compatible Cytoscape.js core version to function.","package":"cytoscape","optional":false},{"reason":"Runtime dependency for the core CoSE logic, introduced in v4.1.0 as part of a refactoring effort.","package":"cose-base","optional":false}],"imports":[{"note":"The module exports the layout as a default-like export. It is then registered using `cytoscape.use()`.","wrong":"import { coseBilkent } from 'cytoscape-cose-bilkent';","symbol":"coseBilkent","correct":"import coseBilkent from 'cytoscape-cose-bilkent';\ncytoscape.use(coseBilkent);"},{"note":"For CommonJS environments, `require` returns the module object which must be passed to `cytoscape.use()`.","wrong":"require('cytoscape-cose-bilkent')();","symbol":"coseBilkent (CommonJS)","correct":"const coseBilkent = require('cytoscape-cose-bilkent');\ncytoscape.use(coseBilkent);"},{"note":"Ensure the layout name is precisely 'cose-bilkent' after registration, not just 'cose'.","wrong":"cy.layout({ name: 'cose', ...options }).run();","symbol":"cy.layout({ name: 'cose-bilkent' })","correct":"cy.layout({ name: 'cose-bilkent', ...options }).run();"}],"quickstart":{"code":"import cytoscape from 'cytoscape';\nimport coseBilkent from 'cytoscape-cose-bilkent';\n\n// Register the cose-bilkent layout extension with Cytoscape.js\ncytoscape.use(coseBilkent);\n\nconst cy = cytoscape({\n  container: document.getElementById('cy'), // Assumes a div with id='cy' exists\n  elements: [\n    { data: { id: 'a' } },\n    { data: { id: 'b' } },\n    { data: { id: 'c' } },\n    { data: { id: 'parent1' } },\n    { data: { id: 'd', parent: 'parent1' } },\n    { data: { id: 'e', parent: 'parent1' } },\n    { data: { id: 'f' } },\n    { data: { id: 'ab', source: 'a', target: 'b' } },\n    { data: { id: 'ac', source: 'a', target: 'c' } },\n    { data: { id: 'ce', source: 'c', target: 'e' } },\n    { data: { id: 'df', source: 'd', target: 'f' } },\n  ],\n  style: [\n    {\n      selector: 'node',\n      style: {\n        'background-color': '#11479e',\n        'label': 'data(id)',\n      },\n    },\n    {\n      selector: 'node:parent',\n      style: {\n        'background-opacity': 0.3,\n        'background-color': '#ccc',\n      },\n    },\n    {\n      selector: 'edge',\n      style: {\n        'width': 4,\n        'line-color': '#9dbaea',\n        'target-arrow-color': '#9dbaea',\n        'target-arrow-shape': 'triangle',\n        'curve-style': 'bezier',\n      },\n    },\n  ],\n  layout: {\n    name: 'preset' // Initial layout, will be overridden by cose-bilkent\n  }\n});\n\n// Apply the cose-bilkent layout\ncy.layout({\n  name: 'cose-bilkent',\n  nodeDimensionsIncludeLabels: true,\n  fit: true,\n  padding: 20,\n  randomize: true,\n  nodeRepulsion: 4500,\n  idealEdgeLength: 50,\n  edgeElasticity: 0.45,\n  nestingFactor: 0.1,\n  gravity: 0.25,\n  numIter: 2500,\n  tile: true,\n  animate: 'end',\n  animationDuration: 500,\n  quality: 'default' // 'draft', 'default', 'proof'\n}).run();","lang":"typescript","description":"This quickstart initializes a Cytoscape.js instance with a simple graph, including compound nodes, then registers and applies the `cose-bilkent` layout with common configuration options, demonstrating its ability to arrange nested structures."},"warnings":[{"fix":"Upgrade your Cytoscape.js dependency to `^3.2.0` or higher to use `cytoscape-cose-bilkent@4.x.x`.","message":"Version 4.0.0 introduced a breaking change, requiring Cytoscape.js version `^3.2.0` or newer. Older Cytoscape.js versions are no longer supported.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"For non-npm setups, ensure `cose-base` and `layout-base` are loaded as global scripts prior to `cytoscape-cose-bilkent`. For npm users, no direct action is needed as `npm install` manages these.","message":"Version 4.1.0 refactored core logic into new external packages (`cose-base` and `layout-base`). While npm installations handle these dependencies automatically, users integrating via direct HTML/JS file inclusion will need to manually source and include `cose-base` and `layout-base` script files *before* `cytoscape-cose-bilkent`.","severity":"breaking","affected_versions":">=4.1.0"},{"fix":"If supporting older browsers, include a comprehensive polyfill library like `core-js`. For best results, use modern evergreen browsers.","message":"This extension primarily targets modern browsers. Legacy browsers like Internet Explorer may require significant polyfilling (e.g., with `core-js`) to function correctly, due to reliance on modern JavaScript features.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Experiment with `quality` ('draft', 'default', 'proof'), `numIter`, `nodeRepulsion`, and `idealEdgeLength` parameters. For large graphs, consider 'draft' quality or reducing `numIter` for quicker (though potentially less optimal) results.","message":"The layout options significantly impact visual quality and performance. Default options might not be optimal for all graph sizes or structures, potentially leading to slow layouts or undesirable arrangements.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `cytoscape` is fully imported and available before calling `cytoscape.use(coseBilkent)`.","cause":"Attempting to register the layout extension before Cytoscape.js itself has been properly loaded or initialized.","error":"TypeError: cytoscape.use is not a function"},{"fix":"Verify that `import coseBilkent from 'cytoscape-cose-bilkent';` and `cytoscape.use(coseBilkent);` are present and executed before attempting to use the layout, and ensure `name: 'cose-bilkent'` is used in the layout call.","cause":"The `cose-bilkent` extension was not correctly registered with Cytoscape.js using `cytoscape.use(coseBilkent);` or the layout name was misspelled.","error":"Layout 'cose-bilkent' could not be found"},{"fix":"Ensure `const cy = cytoscape({...});` has completed execution and `cy` is a valid Cytoscape.js graph instance before calling `cy.layout()`.","cause":"This usually indicates that the Cytoscape.js instance (`cy`) has not been properly initialized or is not yet available when the layout is attempted to be applied.","error":"Cannot read properties of undefined (reading 'layout')"}],"ecosystem":"npm"}