@cosmograph/react

🌠 Cosmograph React

User-friendly library for integrating the @cosmograph/cosmograph graph visualization library into your React applications. It provides a collection of ready-to-use components, that make it easy to build interactive network visualizations in your React applications.

✨ Features

• Simple React component API for the full power of Cosmograph
• Ready-to-use interactive components: Timeline, Histogram, Legends
• React hook for accessing Cosmograph instance
• Full TypeScript support
• Context provider for sharing Cosmograph state
• Support for refs and React 18

🚀 Quick Start

Install the package:

npm install @cosmograph/react@beta

Get the data, configure the graph and render Cosmograph:

import React, { useEffect, useState } from 'react'
import { Cosmograph, CosmographConfig, prepareCosmographData } from '@cosmograph/react'

// Points and links data can be:
// - Array of objects
// - File (.csv/.tsv, .parquet/.pq, .arrow, .json)
// - URL string to a file
// - Apache Arrow Table (binary data Uint8Array/ArrayBuffer)
// - DuckDB table name if connection is passed into the Cosmograph constructor

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} />
}

CosmographProvider

CosmographProvider connects Cosmograph instance with companion components like CosmographTimeline and CosmographHistogram. Wrap your components with it to enable this connection:

import { CosmographProvider, CosmographHistogram, Cosmograph } from '@cosmograph/react'

function App() {
  ...
  return (
    <CosmographProvider>
      <Cosmograph {...config} />
      // Assuming you have a numeric column "value" in your points data
      <CosmographHistogram accessor={"value"}>
    </CosmographProvider>
  )
}

⚠️ Note: Always place Cosmograph companion components inside CosmographProvider and make sure it has Cosmograph instance inside.

useCosmograph

After surrounding your app with CosmographProvider, the useCosmograph hook can now be used to access the Cosmograph instance.

import { useCosmograph, CosmographProvider } from '@cosmograph/react'

const FitButton = () => {
  const { cosmograph } = useCosmograph()
  
  return (
    <button onClick={() => cosmograph.fitView()}>
      Fit View
    </button>
  )
}

const App = () => {
  ...
  return (
    <CosmographProvider>
      <Cosmograph {...config}/>
      <FitButton />
    </CosmographProvider>
  )
}

❗ Note: useCosmograph must be called within a component that is a direct descendant of the CosmographProvider. Attempting to use it outside of the provider will trigger an error.

Refs

Cosmograph exposes a ref property that can be used to access the underlying Cosmograph instance, giving you direct access to its methods and properties.

import React, { useRef } from 'react'
import { CosmographRef, Cosmograph } from '@cosmograph/react'

function App () {
  ...
  const cosmograph = useRef<CosmographRef>()

  const onClick = (pointIndex: number | undefined) => {
    cosmograph.current?.selectPoint(point)
  }}

  return (
    <Cosmograph {...config} onClick={onClick} ref={cosmograph}/>
  )
}

🌙 Available Components

@cosmograph/react provides few components ready for use:

• Cosmograph: The primary component.
• CosmographTimeline: Offers a timeline feature for visualizing data over time.
• CosmographHistogram: A fully customizable histogram component.
• CosmographSizeLegend: A legend component for visualizing data sizes.
• CosmographTypeColorLegend: A legend component for visualizing data types with colors.
• CosmographRangeColor: A component for visualizing numerical data with colors.
• CosmographBars: A component for visualizing data with categorical bars that allow to search, sort and filter these categories.

✏️ Note: All the components included support refs and can be accessed via useRef or useCallback for developers to have better control and management. Read the docs for more details.

🛸 Issues and Contributing

While currently closed source, we welcome your feedback! Help improve Cosmograph by submitting bug reports and feature ideas in our issues repository.

💫 License

Cosmograph is licensed under the CC-BY-NC-4.0 license and free for any non-commercial usage. If you want to use it in a commercial project, please reach out to us.

👩🏻‍🚀 Contacts

📩 [e-mail] · 👾 Cosmograph Discord channel