Get started

ℹ️

You don’t need TypeScript to use Cosmograph. But we’ll still provide TypeScript types across the documentation as a reference.

Installation

Cosmograph v2 is available on NPM as a React @cosmograph/react library or JavaScript library @cosmograph/cosmograph. Both libraries provide TypeScript support.

npm install @cosmograph/react@beta

Creating a Cosmograph instance

import { Cosmograph, CosmographConfig } from '@cosmograph/react'
 
export const Component = () => {
// Define the configuration
const [cosmographConfig, setCosmographConfig] = useState<CosmographConfig>({
  // ...
})
 
  return (
    <Cosmograph {...cosmographConfig} />
  )
}

Create a configuration for data

Cosmograph input data needs pre-indexing. While these requirements may seem complex, we provide the Cosmograph Data Kit that automatically indexes and transforms your data into the required format.

To use it, you need to create a simple configuration that maps your data fields. At minimum, you must specify a points configuration with pointIdBy property - this tells which field contains the unique identifier for each point in your data.

Points and links data can be provided in any of these formats:

Type	Description
`File`	A file object representing data in formats: - CSV (.csv, .tsv) - JSON (.json) (max 100MB) - Apache Parquet (.parquet, .pq) - Apache Arrow (.arrow)
`string`	A URL string pointing to data in one of the formats listed above
`Table`	An instance of Apache Arrow `Table` with the data
`Uint8Array`, `ArrayBuffer`	A typed array or array buffer containing binary data in Apache Arrow format
`Record<string, unknown>[]`	An array of objects, where each object represents a point (or link) and its properties

Here’s a basic configuration example:

import { CosmographDataPrepConfig } from '@cosmograph/react'
 
const rawPoints: Point[] = [{ id: 'a' }, { id: 'b' }, { id: 'c' }]
 
const rawLinks: Link[] = [
  { source: 'a', target: 'b' },
  { source: 'b', target: 'c' },
  { source: 'c', target: 'a' },
]
 
// Create a config to map your data to meet the Cosmograph's internal requirements
const dataConfig: CosmographDataPrepConfig = {
  points: {
    pointIdBy: 'id',
  },
  // If you don't have links data, you can include only `points`
  links: {
    linkSourceBy: 'source',
    linkTargetsBy: ['target'],
  },
}

Learn different ways to create configuration for your data here.

Get prepared data and configuration

Pass your raw data along with the configuration from the previous step into prepareCosmographData() of Cosmograph Data Kit. This method will return an object containing ready-to-use data and configuration that you can use directly with Cosmograph.

import { prepareCosmographData } from '@cosmograph/react'
 
const { points, links, cosmographConfig } = await prepareCosmographData(dataConfig, rawPoints, rawLinks)

prepareCosmographData() also provides linksSummary and pointsSummary which contain aggregates (like minimum and maximum) for points and links data. These summaries can be helpful for generating color and size scales.

Keep in mind that prepareCosmographData() is an async function and needs to be awaited.

ℹ️

Dealing with large-scale data that needs quick processing? Check out Advanced data usage section to speed up data processing without usage of prepareCosmographData() method.

Passing the data and configuration

After your data and configuration are ready, pass them to Cosmograph:

<Cosmograph
  points={points}
  links={links}
  {...cosmographConfig}
>

ℹ️

Cosmograph configuration can include various properties to customize the graph’s appearance and behavior. Check out full list of properties here.

🚀 Fast setup

Ready-to-use examples with a basic configuration for React and JS/TS.

import React, { useEffect, useState } from 'react'
import { Cosmograph, CosmographConfig, prepareCosmographData } from '@cosmograph/react'
 
const rawPoints = [{ id: 'a' }, { id: 'b' }, { id: 'c' }]
 
const rawLinks = [
  { source: 'a', target: 'b' },
  { source: 'b', target: 'c' },
  { source: 'c', target: 'a' },
]
 
export const component = (): JSX.Element => {
  const [config, setConfig] = useState<CosmographConfig>({})
 
  // Create a config to map your data into Cosmograph's internal format
  const dataConfig = {
    points: {
      pointIdBy: 'id',
    },
    links: {
      linkSourceBy: 'source',
      linkTargetsBy: ['target'],
    },
  }
 
  const loadData = async (): Promise<void> => {
    // Prepare data and config for Cosmograph
    const result = await prepareCosmographData(dataConfig, rawPoints, rawLinks)
 
    if (result) {
      // Update Cosmograph config with prepared output
      const { points, links, cosmographConfig } = result
      setConfig({ points, links, ...cosmographConfig })
    }
  }
 
  // Load data when component is mounted
  useEffect(() => { loadData() }, [])
 
  return <Cosmograph {...config} />
}

import { Cosmograph, prepareCosmographData } from '@cosmograph/cosmograph'
 
const rawPoints = [{ id: 'a' }, { id: 'b' }, { id: 'c' }]
 
const rawLinks = [
  { source: 'a', target: 'b' },
  { source: 'b', target: 'c' },
  { source: 'c', target: 'a' },
]
 
// Create a config to map your data into Cosmograph's internal format
const dataConfig = {
  points: {
    pointIdBy: 'id',
  },
  links: {
    linkSourceBy: 'source',
    linkTargetsBy: ['target'],
  },
}
 
const createCosmograph = async (container: HTMLElement): Promise<void> => {
  // Prepare data and config for Cosmograph
  const result = await prepareCosmographData(dataConfig, rawPoints, rawLinks)
 
  // Create Cosmograph instance from prepared data and config
  if (result) {
    const { points, links, cosmographConfig } = result
    const cosmograph = new Cosmograph(container, { points, links, ...cosmographConfig })
  }
}
 
// Render Cosmograph in the provided container
createCosmograph(document.getElementById('cosmograph-container'))

export const nodes = [
  { id: '1', color: '#88C6FF' },
  { id: '2', color: '#FF99D2' },
  { id: '3', color: [227, 17, 108, 1] },
  { id: '4', index: 3, color: '#7B61FF' },
  { id: '5', index: 4, color: '#00D084' },
  { id: '6', index: 5, color: '#FCB900' },
]
 
export const links = [
  { source: '1', target: '2' },
  { source: '2', target: '3' },
  { source: '3', target: '1' },
  { source: '4', target: '1' },
  { source: '5', target: '2' },
  { source: '4', target: '5' },
  { source: '5', target: '6' },
]

ℹ️

While Cosmograph doesn’t have adaptors to other UI frameworks besides React, you can still integrate it into your Angular, Vue, Svelte, or other app, by using JavaScript code.

Configuration Supported formats