Cosmograph React Wrapper
    
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 graph and machine learning embeddings visualizations in your React applications.
- Simple React component API for the full power of Cosmograph
- Ready-to-use interactive components: Timeline, Histogram, Bars, Legends, Search and even more
- React hook for accessing Cosmograph instance
- Full TypeScript support
- Context provider for sharing Cosmograph state
- Support for refs and React 18
Install the package:
``bash`
npm install @cosmograph/react
Get the data, configure the graph and render Cosmograph:
`typescript
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
// 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
// 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
}
`
CosmographProvider connects Cosmograph instance with companion components like CosmographTimeline and CosmographHistogram. Wrap your components with it to enable this connection:
`javascript
import { CosmographProvider, CosmographHistogram, Cosmograph } from '@cosmograph/react'
function App() {
...
return (
// Assuming you have a numeric column "value" in your points data
)
}
`
> _⚠️ Note:_ Always place Cosmograph companion components inside CosmographProvider and make sure it has Cosmograph instance inside.
After surrounding your app with CosmographProvider, the useCosmograph hook can now be used to access the Cosmograph instance.
`javascript
import { useCosmograph, CosmographProvider } from '@cosmograph/react'
const FitButton = () => {
const { cosmograph } = useCosmograph()
return (
)
}
const App = () => {
...
return (
)
}
`
> _❗ 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.
Cosmograph exposes a ref property that can be used to access the underlying Cosmograph instance, giving you direct access to its methods and properties.
`javascript
import React, { useRef } from 'react'
import { CosmographRef, Cosmograph } from '@cosmograph/react'
function App () {
...
const cosmograph = useRef
const onClick = (pointIndex: number | undefined) => {
cosmograph.current?.selectPoint(point)
}}
return (
)
}
`
@cosmograph/react provides a set of components connected to the Cosmograph instance and ready for use:
- Cosmograph: The primary component.
- CosmographTimeline: Offers a timeline feature for visualizing data over time.
- CosmographHistogram: A fully customizable histogram component.
- CosmographBars: A component for visualizing data with categorical bars that allow to search, sort and filter these categories.
- CosmographSizeLegend: A legend component for visualizing data sizes.
- CosmographTypeColorLegend: A legend component for visualizing data types with colors.
- CosmographRangeColorLegend: A component for visualizing numerical data with colors.
- CosmographSearch: Powerful search for your Cosmograph data with integrated on-graph selection features.
- CosmographPopup: A component for displaying customizable HTML popups, which can be anchored to specific nodes or coordinates on the graph.
- Handy set of buttons for common graph interactions:
- CosmographButton: A base button component for custom actions.
- CosmographButtonFitView: Automatically adjusts the graph's zoom and position to fit all nodes within the viewport.
- CosmographButtonPlayPause: Toggles the force-directed layout simulation.
- CosmographButtonZoomInOut: Provides buttons for zooming in and out.
- CosmographButtonRectangularSelection: Allows users to select nodes by drawing a rectangle.
- CosmographButtonPolygonalSelection: Allows users to select nodes by drawing a custom polygon.
> _✏️ Note:_ All the components included support refs and can be accessed via useRef or useCallback` for developers to have better control and management. Check out Cosmograph React docs for more details.
While currently closed source, we welcome your feedback! Help improve Cosmograph by submitting bug reports and feature ideas in our issues repository.
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.
@cosmograph/cosmograph - Cosmograph library for JavaScript and TypeScript\
@cosmos.gl/graph - Cosmos.gl graph-rendering engine\
py_cosmograph - Jupyter widget for data science workflows in Python
🌎 cosmograph.app\
📩 hi@cosmograph.app\
👾 Cosmograph Discord channel