🪐 Cosmograph
[](https://www.npmjs.com/package/@cosmograph/cosmograph) [](https://github.com/cosmograph-org/cosmograph/blob/main/LICENSE) [](https://github.com/cosmograph-org/cosmograph-issues/issues) [](https://discord.gg/Rv8RUQuzsx) [](https://cosmograph.app/docs/get-started/)
A powerful JavaScript graph visualization library built around a **GPU-accelerated force layout** engine. It is especially suited to **knowledge graphs**—large networks of entities, relationships, and ontologies you need to see and navigate in the browser—as well as **semantic maps** from machine learning embeddings. Cosmograph keeps those graphs responsive at scale and pairs the renderer with interactive tools for search, filtering, and exploration.
## ✨ Features
- 🕸️ **Knowledge-graph friendly**: visualize entity–relationship networks at scale, with layouts and interactions that help you spot structure, neighborhoods, and outliers
- 🧠 High-performance processing of millions of points and edges on modern hardware
- 🧩 Ready-to-use interactive components including a timeline, search, histograms, legends, and more.
- 🛠️ Flexible configuration API for full customization over graph behavior and appearance
- 🎨 Rich set of automatic data-based coloring and sizing strategies for points and links
- ✨ Real-time addition, removal, and positioning of points and links
- 📊 Support for standard data formats including `.csv`, `.parquet`, `.arrow` and `.json`
- 🔍 SQL capabilities for powerful data transformations and filtering
- 🔗 Direct connection to tables in external DuckDB instances
- ⌨️ TypeScript support featuring comprehensive types and API hints
## 🚀 Quick Start
1️⃣ Install the package:
```sh
npm install @cosmograph/cosmograph
```
2️⃣ Get the data, configure the graph and render Cosmograph in the provided container:
```typescript
import { Cosmograph, prepareCosmographData } from '@cosmograph/cosmograph'
// 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' },
]
// 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 => {
// 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'))
```
Check out the [Cosmograph documentation](https://cosmograph.app/docs-lib/) for more information and examples.
## 🛸 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](https://github.com/cosmograph-org/cosmograph-issues).
## 💫 License
Cosmograph is licensed under the [CC-BY-NC-4.0 license](https://creativecommons.org/licenses/by-nc/4.0/deed.en) and free for any non-commercial usage. If you want to use it in a commercial project, please [reach out to us](mailto:licensing@cosmograph.app).
## 🌌 Cosmograph Universe
[@cosmograph/react](http://www.npmjs.com/package/@cosmograph/react) - Cosmograph for React applications\
[py_cosmograph](https://github.com/cosmograph-org/py_cosmograph) - Jupyter widget for data science workflows in Python
## 👩🏻🚀 Contacts
🌎 [cosmograph.app](https://cosmograph.app)\
📩 [hi@cosmograph.app](mailto:hi@cosmograph.app)\
👾 [Cosmograph Discord channel](https://discord.gg/Rv8RUQuzsx)