# @joint/react
A React library for building interactive diagrams, flowcharts, and graph-based visualizations. This library provides React components and hooks that wrap JointJS, making it easy to create powerful diagramming applications.
## What can you build with @joint/react?
- ๐ Flowcharts and process diagrams
- ๐ Network topology visualizations
- ๐ง Mind maps and organization charts
- โ๏ธ State machines and workflow editors
- ๐ Any interactive connected graphs
## Why @joint/react?
- ๐ฏ **React-First**: React components and hooks for modern React applications
- ๐ **Easy Integration**: Simple drop-in components with minimal setup
- ๐จ **Customizable**: Full control over node and link appearances
- โก **Interactive**: Built-in support for dragging, connecting, and editing
- ๐ญ **Type-Safe**: Written in TypeScript with full type definitions
## Prerequisites
Before installing @joint/react, ensure you have:
- React 16.8+ (for Hooks support)
- Node.js 14+
- A modern browser (Chrome, Firefox, Safari, Edge)
## Installation
Install the library using your preferred package manager:
```sh
# Using npm
npm install @joint/react
# Using yarn
yarn add @joint/react
# Using bun
bun add @joint/react
```
## Documentation
The documentation is available online:
- [API reference](https://react.jointjs.com/api/index.html)
- [Storybook with examples](https://react.jointjs.com/learn/?path=/docs/introduction--docs)
## Core Concepts
Before diving into the code, let's understand the basic building blocks:
- **Elements**: Nodes in your diagram (boxes, circles, or custom shapes)
- **Links**: Connections between elements (lines, arrows, or custom connectors)
- **Paper**: The canvas (UI) where your diagram is rendered
- **Graph**: The data model that holds your diagram's structure
## Quick Start
Here's a complete example of a simple diagram with two connected nodes:
```tsx
import React, { useCallback } from 'react';
import { GraphProvider, Paper, createElements, createLinks } from '@joint/react';
// Define your diagram elements (nodes)
const initialElements = createElements([
{
id: '1',
label: 'Start',
x: 100, // Position from left
y: 50, // Position from top
width: 120,
height: 60
},
{
id: '2',
label: 'End',
x: 100,
y: 200,
width: 120,
height: 60
},
]);
// Define connections between elements
const initialLinks = createLinks([
{
id: 'link1',
source: '1', // ID of source element
target: '2' // ID of target element
}
]);
// Main component that renders the diagram
function DiagramExample() {
// Define how each element should look
const renderElement = useCallback((element) => (
{element.label}
), []);
return (
);
}
// Wrap your app with GraphProvider
export default function App() {
return (
);
}
```
## Event Handling
@joint/react provides various events to handle user interactions:
```tsx
function DiagramExample() {
const handleElementClick = useCallback((element) => {
console.log('Element clicked:', element);
}, []);
return (
);
}
```
## TypeScript Support
@joint/react is written in TypeScript and includes comprehensive type definitions. Here's an example of using types:
```tsx
import { InferElement } from '@joint/react';
const elements = createElements([
{ id: '1', label: 'Node', x: 0, y: 0, width: 100, height: 40 }
]);
type CustomElement = InferElement;
const renderElement = (element: CustomElement) => (
{element.label}
);
```
## Performance Considerations
To ensure optimal performance:
1. **Memoization**
```tsx
// Memoize render functions
const renderElement = useCallback((element) => {
return ;
}, []);
// Memoize event handlers
const handleElementClick = useCallback((element) => {
// Handle click
}, []);
```
## ๐ Core Components
### 1. **GraphProvider**
The `GraphProvider` component manages a shared [JointJS Graph instance](https://docs.jointjs.com/api/dia/Graph/) to handle the state of your diagram. Wrap it around any components that interact with the graph.
```tsx
import { GraphProvider } from '@joint/react';
{/* Components like Paper for rendering nodes and edges */}
```
### 2. **Paper**
The `Paper` component wraps [JointJS Paper](https://docs.jointjs.com/learn/quickstart/paper/) to render nodes and links. Use the `renderElement` prop to define how nodes are displayed.
```tsx
import { Paper } from '@joint/react';
const renderElement = (element) => (
);
```
### 3. **Rendering HTML Elements**
Although JointJS is SVG-based, you can render HTML content inside nodes using SVG's ``:
```tsx
const renderElement = ({ width, height }) => (
HTML Content here
);
```
## ๐ ๏ธ Core Hooks and Utilities
### ๐น Accessing Elements
- `useElements()`: Retrieve all diagram elements (requires `GraphProvider` context).
- `useElement()`: Retrieve individual element data, typically used within `renderElement`.
### ๐น Modifying Elements
- `useUpdateElement()`: Update existing elements in the diagram.
- `useCreateElement()`: Create new elements in the diagram.
- `useRemoveElement()`: Remove elements from the diagram.
- `useCreateLink()`: Create new elements in the diagram.
- `useRemoveLink()`: Remove elements from the diagram.
### ๐น Graph and Paper Instances
- `useGraph()`: Access the [dia.Graph](https://docs.jointjs.com/api/dia/Graph/) instance directly.
- `usePaper()`: Access the [dia.Paper](https://docs.jointjs.com/learn/quickstart/paper) instance directly.
### ๐น Creating Nodes and Links
- `createElements()`: Utility for creating nodes.
```ts
import { createElements } from '@joint/react';
const initialElements = createElements([
{ id: '1', type: 'rect', x: 10, y: 10, width: 100, height: 100 },
]);
```
- `createLinks()`: Utility for creating links between nodes.
```ts
import { createLinks } from '@joint/react';
const initialLinks = createLinks([
{ source: '1', target: '2', id: '1-2' },
]);
```
---
## How It Works
Under the hood, **@joint/react** listens to changes in the `dia.Graph`, which acts as the single source of truth. When you update the graphโsuch as adding or modifying cellsโthe React components automatically observe and react to these changes, keeping the UI in sync.
Hooks like `useUpdateElement` provide a convenient way to update the graph, but you can also directly access the graph using `useGraph()` and call methods like `graph.setCells()`.
---
## Known Issues and Recommendations
### Avoid Certain CSS Properties in ``
Some CSS properties can cause rendering issues in Safari when used inside an SVG ``. To ensure compatibility, avoid the following properties:
- `position` (other than `static`)
- `-webkit-transform-style`
- `-webkit-backface-visibility`
- `transition`
- `transform`
### Recommended Workaround
If you need to use HTML inside an SVG with cross-browser support:
- Use minimal CSS inside ``.
- Stick to static positioning and avoid CSS transforms.
- Consider overlaying HTML outside the SVG using absolute positioning.
### Flickering
React's asynchronous rendering can cause flickering when dynamically adding ports or resizing elements. We are aware of this issue and are working on a fix.
### Controlled Mode
Currently, **@joint/react** uses `useSyncExternalStore` to listen to graph changes. The graph is the source of truth, so `initialElements` and `initialLinks` are only used during initialization. To modify the state, update the graph directly using hooks like `useGraph`, `useUpdateElement`, or `useCreateElement`. A fully controlled mode is under development.
