Labels

Cosmograph allows you to display labels for points and clusters to provide context and identification for your data elements. You can control which labels are shown, their appearance, and their priority.

Point labels

To display labels for points, you need to specify which data column contains the label text using the pointLabelBy property.

You must also enable labels globally by setting showLabels to true.

const config = {
  // ...
  points: [
    { id: '1', name: 'Alpha', importance: 10 },
    { id: '2', name: 'Beta', importance: 5 },
    // ...
  ],
  pointLabelBy: 'name',
  showLabels: true
}

const points = [
  { id: '1', firstName: 'John', lastName: 'Doe' },
  { id: '2', firstName: 'Jane', lastName: 'Smith' },
  // ...
]
 
const config = {
  // ...
  points,
  // pointLabelBy is required for pointLabelFn to work
  pointLabelBy: 'firstName', 
  // Use index to access the full point object from the data array
  pointLabelFn: (value, index) => `${value} ${points[index].lastName}`,
  showLabels: true
}

Visibility control

Cosmograph provides several ways to control which labels are displayed to avoid clutter:

Weight

You can influence which labels are prioritized using the following properties:

const config = {
  // ...
  pointLabelWeightBy: 'importance',
  // normalize / clamp any data into 0..1
  pointLabelWeightFn: (value) => Math.max(0, Math.min(1, Number(value) / 100)),
}

If not provided, labels are prioritized based on:

1. pointSizeBy (if provided)
2. Point degree (total number of links)

Style

You can customize the appearance of point labels:

Hovering

You can display a label when hovering over a point using showHoveredPointLabel.

const config = {
  // ...
  pointLabelBy: 'id',
  showHoveredPointLabel: true,
  hoveredPointLabelClassName: 'my-custom-tooltip' // optional
}

This label uses the same text source as defined in pointLabelBy or pointLabelFn.

Interactivity

You can control how users interact with point labels through these props:

const config = {
  // ...
  selectPointOnLabelClick: true,
  onLabelClick: (index, id) => {
    console.log('Clicked label:', { index, id })
  },
}

Advanced configuration

Cluster labels

Cluster labels provide a high-level overview of the graph structure. To use them, you must have clustering enabled via pointClusterBy.

Enable cluster labels by setting showClusterLabels to true.

const config = {
  // ...
  pointClusterBy: 'group',
  showClusterLabels: true,
}

Style

Interactivity

You can control how users interact with cluster labels through these props:

const config = {
  // ...
  selectClusterOnLabelClick: true,
  onClusterLabelClick: (clusterIndex, clusterId) => {
    console.log('Clicked cluster label:', { clusterIndex, clusterId })
  },
}

Custom labels

You can manually add labels to the graph using the customLabels property. This is useful for annotations or highlighting specific areas unrelated to data points.

const config = {
  // ...
  customLabels: [
    { text: 'My Label', position: [100, 200] },
    { text: 'Important Area', position: [500, 300], className: 'myCustomLabel' }
  ]
}

The customLabels property expects an array of objects with the following properties: