Hot Data Update

Cosmograph allows you to dynamically add or remove points and links without reloading the entire dataset. This is particularly useful for real-time applications, streaming data, or interactive explorations where the graph structure changes over time.

Getting Started

To add or remove data dynamically, you’ll need a reference to your Cosmograph instance.

import { useRef } from 'react'
import { Cosmograph, CosmographRef } from '@cosmograph/react'
 
const MyGraph = () => {
  const cosmograph = useRef<CosmographRef>(null)
 
  return (
    <Cosmograph
      ref={cosmograph}
      // ... other props
    />
  )
}

Adding Data

You can append new points and links to the existing graph using addPoints and addLinks.

Adding Points

Use addPoints with an array of new point objects. Each point should have the same properties as your existing data.

const addMyPoints = async () => {
  const newPoints = [
    { id: 'new-1', value: 10, color: '#ff0000' },
    { id: 'new-2', value: 20, color: '#00ff00' },
  ]
  
  await cosmograph.current?.addPoints(newPoints)
}

Adding Links

Use addLinks to create new connections between points.

const addMyLinks = async () => {
  const newLinks = [
    { source: 'new-1', target: 'new-2' },
    { source: 'existing-point', target: 'new-1' },
  ]
  
  await cosmograph.current?.addLinks(newLinks)
}

Removing Data

You can remove points and links by ID or by index. For large datasets, using indices is faster.

Removing Points

// Removes points at indices 0, 1, and 2
// The second argument `true` (default) automatically removes any attached links
await cosmograph.current?.removePointsByIndices([0, 1, 2], true)

// Removes points with specific IDs
await cosmograph.current?.removePointsByIds(['node-a', 'node-b'])

Removing Links

Links can be removed by specifying the pairs of points they connect, either by IDs or by indices.

// Remove the link between 'node-a' and 'node-b'
await cosmograph.current?.removeLinksByPointIdPairs([
  ['node-a', 'node-b']
])

// Remove the link between points at indices 0 and 5
await cosmograph.current?.removeLinksByPointIndicesPairs([
  [0, 5]
])

Working With Simulation

When adding or removing data, you may want to control how the simulation responds to keep your layout stable.

Keep Existing Positions

By default, adding data can cause the entire graph to re-layout. To keep existing points in place while new points settle in, use preservePointPositionsOnDataUpdate.

<Cosmograph
  // ...
  preservePointPositionsOnDataUpdate={true}
  enableSimulation={true}
/>

Pin Specific Points

You can lock specific points in place while the rest of the graph moves freely.

// Pin the first 3 points (indices 0, 1, 2)
cosmograph.current?.setPinnedPoints([0, 1, 2])
 
// Unpin all points
cosmograph.current?.setPinnedPoints([])

Examples

Explore these interactive examples to see hot data updates in action:

Adding and Removing Data Items

A basic example demonstrating how to add and remove individual points and links. Features include:

• Adding single or multiple points at once
• Removing points by index
• Adding and removing links dynamically
• Histogram reacting to data changes

Dynamic Data with Positions Control

An advanced example showing how to manage data updates while controlling the simulation. Features include:

• Adding and removing entire subsets of connected points
• Using preservePointPositionsOnDataUpdate to keep existing positions stable
• Pinning specific points during simulation
• Controlling drag behavior during updates

API Reference