Release v2.5

🎉 What's New

Link Hover Detection

Screen.Recording.2025-09-11.at.07.43.07.web.mp4

const config = {
  hoveredLinkColor: '#ff3333',
  hoveredLinkWidthIncrease: 4,
  hoveredLinkCursor: 'pointer',
  
  onLinkMouseOver: (linkIndex) => {
    console.log(`Hovering over link ${linkIndex}`);
  },
  
  onLinkMouseOut: (event) => {
    console.log('Mouse left link');
  },
  
  onLinkClick: (linkIndex, event) => {
    console.log(`Clicked link ${linkIndex}`);
  }
};

Link Hover Configuration Options

Fine-tune the link hover experience with new configuration properties:

• hoveredLinkColor - Color for hovered links (hex string or RGBA array)
• hoveredLinkWidthIncrease - Additional pixels to add to link width on hover (default: 5)
• hoveredLinkCursor - Cursor style when hovering over links (default: 'auto')

New Mouse Event Callbacks

Added comprehensive mouse event handling for enhanced interactivity:

• onLinkMouseOver(linkIndex) - Called when mouse enters a link
• onLinkMouseOut(event) - Called when mouse leaves a link
• onLinkClick(linkIndex, event) - Called when a link is clicked
• onPointClick(index, position, event) - Called when a point is clicked
• onBackgroundClick(event) - Called when clicking empty space

Enhanced API with unpause() Method

Added a new unpause() method to replace the deprecated restart() method and onSimulationUnpause config option added instead of onSimulationRestart.

// New recommended approach
graph.unpause();

// Deprecated (still works but will be removed)
graph.restart();

Check out the new Link Hovering story in the documentation for a complete working example!

Release v2.4

🎉 What's New

Multiple Point Shapes Support with new API method setPointShapes

You can now assign Circle, Square, Triangle, Diamond, Pentagon, Hexagon, Star and Cross shapes to individual points in your graph. All points default to Circle shape.

graph.setPointShapes(new Float32Array([
  PointShape.Circle, 
  PointShape.Square, 
  PointShape.Triangle, 
  // ...
]));

Custom Image Rendering Support

Added support for image rendering on points. Custom images are drawn on top of shapes. New API methods added:

• setImageData(imageDataArray) - Set the images to use for points
• setPointImageIndices(imageIndices) - Specify which image each point should use
• setPointImageSizes(imageSizes) - Set custom sizes for each point's image

const imageData = new ImageData(/* your image data */);
graph.setImageData([imageData]);
graph.setPointImageIndices(new Float32Array([0, 0, 0])); // Use image 0 for all points

Enhanced View Fitting with new configuration property fitViewByPointIndices

Configure automatic view fitting to specific point indices during graph initialization.

🔧 Improvements

Rendering and Performance Enhancements

• Enhanced Arrow Scaling: Improved arrow scaling logic for better visual representation across different zoom levels
• Selected Points Priority: Selected points now render in front of unselected points, improving visibility and user interaction feedback
• Tracked positions optimization: Getting tracked point positions (getTrackedPointPositionsMap() method) is now significantly faster when simulation isn't running, preventing lag in static visualizations

Code Quality

• ESLint improvements: Added @typescript-eslint/naming-convention rules for consistent code style

---

⚠️ Breaking Changes

API Return Type Changes

• getTrackedPointPositionsMap() method now returns a ReadonlyMap instead of a Map

Migration Guide: If you were modifying the returned map from getTrackedPointPositionsMap(), you'll need to create a new Map from the ReadonlyMap result.

// Before (breaking)
const positions = graph.getTrackedPointPositionsMap();
positions.set(key, value); // ❌ This will now fail

// After (fixed)
const positions = new Map(graph.getTrackedPointPositionsMap());
positions.set(key, value); // ✅ This works

Release v2.3

🎉 What's New

New API Methods

• getTrackedPointPositionsArray - Optimized method for tracking point positions with better performance
• getSampledPoints - Retrieve point data as arrays for efficient data processing
• getPointColors - Get point colors as arrays
• getPointSizes - Get point sizes as arrays
• getLinkColors - Get link colors as arrays
• getLinkWidths - Get link widths as arrays

New Configuration Properties

• linkOpacity - Universal opacity control for links
• pointOpacity - Universal opacity control for points

🔧 Improvements

Performance Enhancements

• Simulation Optimization: Prevented unnecessary simulation restarts when rendering with alpha=0 after pause
• Tracking Optimization: Added optimized point position tracking with getTrackedPointPositionsArray

API Improvements

• Method Renaming: Renamed methods for better clarity while maintaining backward compatibility:
  • getPointsInRange → getPointsInRect (old name kept as deprecated alias)
  • selectPointsInRange → selectPointsInRect (old name kept as deprecated alias)
  • Lasso selection methods renamed to polygon selection methods

🐛 Bug Fixes

• Arrow Rendering: Fixed arrow size width issue in line drawings

🔒 Security

• XSS Protection: Added DOMPurify HTML sanitization to prevent cross-site scripting attacks

🔄 Breaking Changes

Method Renaming

While backward compatibility is maintained through deprecated aliases, the following methods have been renamed:

• getPointsInRange → getPointsInRect
• selectPointsInRange → selectPointsInRect
• Lasso selection methods → Polygon selection methods

Migration Guide: The old method names will continue to work but are deprecated. Update your code to use the new method names to avoid deprecation warnings.

Release v2.2

• Added lasso/polygon selection functionality for advanced point selection (#152 )

Release v2.1

✨ Added

• Position Rescaling: Automatic position rescaling with rescalePositions config option and dontRescale parameter for setPointPositions()
• Simulation During Zoom: New enableSimulationDuringZoom option to continue simulation while zooming
• Right-Click Repulsion: Added enableRightClickRepulsion for interactive force manipulation
• Link Width Scaling: New scaleLinksOnZoom configuration option
• Point Greying: Added pointGreyoutColor for dynamic point dimming
• Custom Attribution: HTML-based attribution system with attribution config option
• Enhanced Error Handling: WebGL initialization error handling with custom styling
• Enhanced Storybook examples, README and API documentation

🔧 Changed

• Configuration Renaming:
  • disableSimulation → enableSimulation
  • disableZoom → enableZoom
  • disableRescalePositions → rescalePositions
  • useQuadtree → useClassicQuadtree
  • showAttribution → attribution
• Default Values: scalePointsOnZoom default changed to false
• CSS Variables: Updated to --cosmosgl-attribution-color and added --cosmosgl-error-message-color
• Project Rebranding: Renamed to cosmos.gl (@cosmos.gl/graph)
• Enhanced Destroy Method

🐛 Fixed

• Point tracking behavior on position updates
• Graph initialization for screen and space size
• Cluster position array length calculation
• Framebuffer initialization stability

🗑️ Removed

• setFocusedPointByIndex method (use focusedPointIndex config instead)

📦 Dependencies

• Updated Vite, ESBuild, Storybook, and other development dependencies
• Updated Store2 to 2.14.4

⚠️ Breaking Changes

• Configuration property names changed (see Changed section)
• setFocusedPointByIndex method removed
• CSS variable names updated

2.0

🪐 Cosmos 2.0 Public Beta

cosmos-2.0.mp4

Cosmos 2.0 goes low level to give you even better performance! Check out the migration guide and our Storybook app for more details.

New features:

• Point Dragging
• Clustering Force
• Configurable Link Strength

Current release is a public beta but it should be stable enough to try it out!

Also we're announcing Cosmograph for 🐍 Python! More about it — on our website.

Release v1.6

What's new

• Support for accessor function in linkArrows: Added support for using accessor function in linkArrows to customize the appearance of the arrows. This feature was contributed by WanQiyang.
• Support for linking to minified library: Added support for linking to the minified version of the library through jsDelivr CDN links.
• Initial zoom behavior updates: The initialZoomLevel configuration parameter is now undefined by default. If initialZoomLevel is set, the view will not be fit to the initial zoom level.
• Zoom the view without d3 transition: Zoom the view without d3 transition if the duration parameter is 0.
• Support color with transparency in backgroundColor configuration property: For example, rgba(0, 0, 0, 0) would set the background color to black with no opacity. Thanks miklevin for raising issue in the cosmograph-issues repository (cosmograph-org/cosmograph-issues#14).
• Improved point detection accuracy on mouse hover
• Paddings when Fitting the View: When fitting the view, the paddings are now taken into account as a percentage of the view size.

Fixes

• Canvas Resizing: Previously, centering of the view was lost when resizing the canvas. Now, the centering is saved during resizing.

Optimization

• Prevent Maximum call stack size exceeded: Calculating the minimum and maximum values using Math.min and Math.max with spread operators can lead to Maximum call stack size exceeded error, especially when dealing with large arrays. To address this issue, the d3-array extend method is used instead, which is more memory-efficient and provides the same functionality.

Bumps

• ttypescript from 1.5.13 to 1.5.15

Release v1.5

Cosmograph 1.5 brings a few exciting new features, along with bug fixes and optimizations.

What's new

• Node Sampling: A new method getSampledNodePositionsMap has been introduced to enable you to sample a number of evenly distributed nodes visible on the screen. It comes in handy when you want to implement feature like dynamic node labels. You can control the number of nodes in the sample by specifying the nodeSamplingDistance configuration parameter. Thanks to this feature, we were able to introduce dynamic node labels in the latest Cosmograph.app update:

• Fitting Nodes in the Scene on Initialization: Cosmos will now center and zoom the view to include all nodes in the scene upon initialization. You can use the following configuration options to control this behavior: fitViewOnInit, fitViewDelay, and fitViewByNodesInRect.

• Rescaling Initial Position of Nodes: To avoid issues related to nodes having coordinates outside the simulation space boundaries, Cosmos will now rescale the initial coordinates of the nodes to fit within the simulation space if the simulation is active. This is useful when you load a graph with pre-calculated initial coordinates and want Cosmos to calculate the force layout for it.

Fixes

• We have resolved the issue of switching between curve/straight line rendering after Cosmos initialization.

Optimization

• Node sizes are now stored in an array for faster access.

Release v1.4

In version 1.4 Cosmos introduces features like curved links, enhanced node focus/hover distinctions with new configurations, options for initial zoom level and disabling zoom/simulation, and more.

What's new:

• Curved Links: The curvedLinks config parameter turns line curvature on/off.

• New onTick callback arguments: The hovered node, index, and nodePosition are now available as second, third, and fourth callback arguments.

• Hovered and focused nodes introduced: We've separated the highlighted nodes into two categories: hovered and focused nodes. We also added new methods to control the focused node such as setFocusedNodeById and setFocusedNodeByIndex. Additionally, we have introduced new configuration parameters that allow for more customization, such as renderHoveredNodeRing, hoveredNodeRingColor, and focusedNodeRingColor. These new changes will be available alongside the old configurations to ensure compatibility until version 2.0. For more detailed information, please see our wiki page.

• Adjusted transparency of the hovered and focused node's ring:** The transparency of the hovered and focused node's ring is now inherited from the parent node.

• Assigning the initial zoom level to the graph when it is first created: The `initialZoomLevel' configuration parameter can be set once during graph initialization.

• Disable Zooming. If the disableZoom configuration parameter is set to true, zooming in and out using the mouse wheel is disabled.

• Cosmos can be run without the simulation, e.g. if you just want to visualize your data set with provided node coordinates. Use the disableSimulation config parameter to turn on that behavior (please note that it can be set on graph initialization only).

Fixes:

• Smart destruction of WebGL buffers and frame buffers and preventing a zero-sized texture from attaching to a WebGL frame buffer.

• Cosmos will not crash if there are no nodes or links.

• Fixed the fitView method execution, when calling before the animation starts.

• Adjusting spaceSize if it exceeds the WebGL limit (#49 (comment)).

• Cosmos can now run the simulation even if the graph contains only nodes and no links.

• We made the graph property public in the main Graph class (where the data processing takes place).

• Added a second argument - index to the config accessor functions nodeSize and nodeColor.

Optimization

• We have improved the method for finding the hovered node to minimize the chance of slowdowns or lags.

Other

• We've also added a citation file that you can use if you use Cosmos or Cosmograph.

Release v1.3

Release 1.3 of Cosmos implements a bunch of new features making your work with graphs way more comfortable. Our personal highlight is the trackNodePositionsBy methods allowing you to continuously get coordinates for chosen nodes and render labels for them.

We deliberately decided not to add labels rendering functionality to Cosmos itself to keep the library tiny. Instead we've created a separate package @interacta/css-labels that you can use along with Cosmos to add labels to your graph. Check out this CodeSanbox example for copy-pastable sample code.

What's new:

• 🤖 New API methods getNodeRadiusByIndex, getNodeRadiusById, spaceToScreenPosition, spaceToScreenRadius, trackNodePositionsByIds, trackNodePositionsByIndices and getTrackedNodePositionsMap;
• 🌱 Random seed. You can now provide randomSeed in the config. It allows you to control the randomness of the layout across different simulation runs. This feature was implemented thanks to @jorrit-hdrn's feedback in issue #19;
• 🖱️ Mouse events. You can now add callbacks to onMouseMove, onNodeMouseOver and onNodeMouseOut events in the config;
• ⚪ Highlight nodes with a ring when hovered or clicked. Config properties renderHighlightedNodeRing allow you to turn on/off highlighting and highlightedNodeRingColor allow you to set the color of the ring #24;
• 🔍 Define scale when zooming to a node programmatically. New arguments scale and canZoomOut are available in the zoomToNodeById and zoomToNodeByIndex methods;
• 👨‍💻 Renamed Types: InputNode to CosmosInputNode and InputLink to CosmosInputLink (old naming will also be available till version 2.0 to preserve compatibility).