šŸŖ Cosmograph Library 2.0 and Python Widget beta release. Read more ā†’
JavaScript & React libraryGet started

Get started

ā„¹ļø

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

Installation


NPM Version (with dist tag)

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
FileA file object representing data in formats:
- CSV (.csv, .tsv)
- JSON (.json) (max 100MB)
- Apache Parquet (.parquet, .pq)
- Apache Arrow (.arrow)
stringA URL string pointing to data in one of the formats listed above
TableAn instance of Apache Arrow Table with the data
Uint8Array, ArrayBufferA 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} />
}

ā„¹ļø

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.

Supported formats