[](https://github.com/ts-graphviz/ts-graphviz/actions/workflows/main.yaml)
[](https://github.com/ts-graphviz/ts-graphviz/actions/workflows/codeql-analysis.yml)
[](https://github.com/ts-graphviz/ts-graphviz/blob/main/LICENSE)
[](#contributors-)
[](https://www.bestpractices.dev/projects/8396)
[](https://scorecard.dev/viewer/?uri=github.com/ts-graphviz/ts-graphviz)
[](https://tidelift.com/subscription/pkg/npm-ts-graphviz?utm_source=npm-ts-graphviz&utm_medium=readme)
[](https://badge.fury.io/js/ts-graphviz)
[](https://github.com/denoland/deno)
[](https://npmtrends.com/ts-graphviz)
# @ts-graphviz/react
React Components and Renderer for ts-graphviz
🔗
[](https://github.com/ts-graphviz/ts-graphviz)
[](https://www.npmjs.com/package/ts-graphviz)
[](https://ts-graphviz.github.io/ts-graphviz/)
[](https://deepwiki.com/ts-graphviz/ts-graphviz)
[](https://github.com/sponsors/ts-graphviz)
[](https://opencollective.com/ts-graphviz)
[](https://biomejs.dev/)
[](https://vitest.dev/)
[](https://rollupjs.org/)
---
> It is part of the ts-graphviz library, which is split into modular packages to improve maintainability, flexibility, and ease of use.
## Installation
The module can then be installed using [npm](https://www.npmjs.com/):
[](https://nodei.co/npm/@ts-graphviz/react/)
```bash
# yarn
$ yarn add @ts-graphviz/react react@^19
# or npm
$ npm install -S @ts-graphviz/react react@^19
# or pnpm
$ pnpm add @ts-graphviz/react react@^19
```
> **Important**: Install React 19+ as a peerDependency. React 18 and earlier versions are not supported. Note that `react-dom` is no longer required as this package now uses a custom HTML rendering implementation.
## Key Features
## React Component
### Core Components
The package provides React components that map directly to Graphviz DOT language constructs:
#### Graph Containers
- **``** - Creates a directed graph (arrows point from source to target)
- **``** - Creates an undirected graph (no arrow direction)
- **``** - Creates a subgraph cluster for grouping related nodes
#### Graph Elements
- **``** - Creates a node/vertex with customizable attributes
- **``** - Creates an edge/connection between nodes with optional styling
### Component Props & Attributes
All components accept Graphviz DOT attributes as props with full TypeScript support:
```tsx
// Node with styling attributes
{/* nodes and edges */}
```
### Nested Structure & Composition
Components can be freely nested to create complex graph structures:
```tsx
// Define reusable components
const ServerNode = ({ id, name, type }) => (
{name}
{type}
}
shape="record"
/>
);
const ServiceCluster = ({ id, label, children }) => (
{children}
);
// Compose the architecture
const SystemArchitecture = () => (
);
```
### HTML-Like Labels with JSX
Create rich, formatted labels using Graphviz's HTML-like label syntax with natural JSX:
```tsx
// Reusable table component for data records
const DataRecord = ({ title, fields }) => (
{title}
{fields.map(([key, value]) => (
{key}
{value}
))}
);
// Status indicator component
const StatusIndicator = ({ status, message }) => (
<>
Status:
{status.toUpperCase()}
{message}
);
// Usage in graph
const DatabaseDiagram = () => (
);
```
### Available HTML-Like Elements
- ``, ``, `` - Table structures
- ``, ``, `` - Text formatting (bold, italic, underline)
- `` - Font styling with color, face, point-size
- `` - Line breaks
- ``, `` - Horizontal/vertical rules
- `` - Images
- ``, ``, ``, `` - Advanced text formatting
### TypeScript Integration
Full type safety with IntelliSense support for all Graphviz attributes:
```tsx
import type { NodeProps, EdgeProps, DigraphProps } from '@ts-graphviz/react';
// Typed component props
const MyNode: React.FC = (props) => (
Name
John Doe
}
shape="box"
/>
```
The `DotJSXElements` type is also exported for advanced use cases where you need to reference the type definitions directly.
#### Enhanced Type Safety
The package provides sophisticated TypeScript support with automatic type inference and runtime type filtering:
```tsx
// ✅ Automatic type inference - no casting needed
const root = createRoot();
await root.render(
);
// ✅ Type-safe model access
const models = root.getTopLevelModels();
// models is automatically typed as DotObjectModel[]
// ✅ Runtime type filtering with built-in type guards
import { isNodeModel, isEdgeModel, isRootGraphModel } from '@ts-graphviz/common';
// Filter by model type with automatic type narrowing
const nodes = root.getTopLevelModels(isNodeModel);
nodes.forEach(node => console.log(node.id)); // TypeScript knows this is NodeModel
const edges = root.getTopLevelModels(isEdgeModel);
edges.forEach(edge => console.log(edge.targets)); // TypeScript knows this is EdgeModel
const graphs = root.getTopLevelModels(isRootGraphModel);
graphs.forEach(graph => console.log(graph.directed)); // TypeScript knows this is RootGraphModel
// ✅ Direct type casting (trusted user assertion)
// When you know the exact types, you can cast directly without runtime validation
const trustedNodes = root.getTopLevelModels();
trustedNodes.forEach(node => console.log(node.id)); // TypeScript trusts your assertion
const trustedEdges = root.getTopLevelModels();
trustedEdges.forEach(edge => console.log(edge.targets)); // No runtime type checking
// ✅ Advanced model type checking
const allModels = root.getTopLevelModels();
for (const model of allModels) {
if (isNodeModel(model)) {
console.log(`Node: ${model.id}`);
} else if (isEdgeModel(model)) {
console.log(`Edge: ${model.targets.map(t => t.id).join(' -> ')}`);
} else if (isRootGraphModel(model)) {
console.log(`Graph: ${model.id} (directed: ${model.directed})`);
}
}
```
#### Container Mode Type Safety
When using container mode, you get access to all rendered models with full type safety:
```tsx
import { digraph } from 'ts-graphviz';
import { isNodeModel, isEdgeModel, isSubgraphModel } from '@ts-graphviz/react';
const container = digraph('myContainer');
const root = createRoot({ container });
await root.render(
<>
);
// Container mode: access all non-container models with type safety
// Runtime type filtering (safe, validates at runtime)
const allNodes = root.getTopLevelModels(isNodeModel); // NodeModel[]
const allEdges = root.getTopLevelModels(isEdgeModel); // EdgeModel[]
const subgraphs = root.getTopLevelModels(isSubgraphModel); // SubgraphModel[]
// Direct type casting (user knows the types, no runtime validation)
const trustedNodes = root.getTopLevelModels(); // All models cast as NodeModel[]
const trustedEdges = root.getTopLevelModels(); // All models cast as EdgeModel[]
// Type-safe operations
allNodes.forEach(node => {
node.attributes.set('color', 'blue'); // TypeScript knows node attributes
});
allEdges.forEach(edge => {
console.log(`Edge from ${edge.targets[0]} to ${edge.targets[1]}`);
});
```
## Core Functions
The package provides clean async rendering APIs:
- `createRoot()` - Creates a rendering root following React 19's createRoot pattern
- `renderToDot()` - Primary async function for converting React components to DOT language strings
- `renderHTMLLike()` - Renders HTML-like label structures for use in node or edge labels
All rendering functions are **async-only** and provide a clean, consistent API surface. The new `createRoot()` API follows React 19's modern patterns for better performance and error handling.
## Usage Examples
### Creating a Simple Graph
```tsx
import { Digraph, Node, Edge, createRoot, renderToDot } from "@ts-graphviz/react";
// Define a reusable process component
const ProcessNode = ({ id, label, color = "lightblue" }) => (
{label}
}
shape="record"
/>
);
// Create a workflow diagram
const WorkflowDiagram = () => (
);
// Create root and render to graph models
const root = createRoot();
await root.render(
{title}
{items.map((item, index) => (
• {item}
))}
}
shape="record"
/>
);
// Usage in graph
const ProjectDiagram = () => (
);
const dotString = await renderToDot(
left
right
);
// With custom security options
const deeplyNestedLabel = renderHTMLLike(
{/* ... deeply nested structure ... */}
,
{ maxDepth: 2000 } // Increase limit for complex structures
);
// Stricter validation for user-generated content
const userContent = renderHTMLLike(
userProvidedElement,
{ maxDepth: 100 } // Lower limit for untrusted input
);
```
#### Security Model: DOT Language vs Browser HTML
**Important**: The HTML-like labels generated by this library are **not browser HTML**. They are:
- Part of the GraphViz DOT language specification
- Processed by the GraphViz engine (not browsers)
- Converted to SVG/PNG/etc. by GraphViz tools
**XSS Risk Context**:
- This library generates DOT strings, not web content
- XSS risks occur when rendering GraphViz output (SVG/HTML) in browsers
- See `@ts-graphviz/adapter` documentation for handling user-provided DOT files safely
#### Security Options
The `renderHTMLLike` function provides security protections against stack overflow attacks:
- **`maxDepth`** (default: `1000`): Maximum recursion depth for nested elements
- Prevents stack overflow from deeply nested or circular structures
- Adjust based on your use case:
- **Increase** for complex, trusted structures (e.g., `maxDepth: 5000`)
- **Decrease** for user-generated content (e.g., `maxDepth: 100`)
- When the limit is exceeded, the function returns a safe fallback value (`'<>'`)
```ts
import { renderHTMLLike, type RenderHTMLLikeOptions } from "@ts-graphviz/react";
// Type-safe options
const options: RenderHTMLLikeOptions = {
maxDepth: 1500
};
const result = renderHTMLLike(... , options);
```
### Advanced Root Options
```ts
import { Digraph, Node, Edge, createRoot } from "@ts-graphviz/react";
// Basic usage
const root = createRoot();
await root.render(
);
// Container mode - render into existing graph
import { digraph } from 'ts-graphviz';
const container = digraph('MyGraph');
const containerRoot = createRoot({ container });
await containerRoot.render(
<>
(null);
const edgeRef = useRef(null);
const digraphRef = useRef(null);
const graphRef = useRef(null);
const handleRender = async () => {
// Example with Digraph component
const digraphRoot = createRoot();
await digraphRoot.render(
);
// Example with Graph component (undirected)
const graphRoot = createRoot();
await graphRoot.render(
);
// Access and manipulate the models directly
if (nodeRef.current) {
nodeRef.current.attributes.set('color', 'red');
nodeRef.current.comment = 'Modified via ref';
}
if (edgeRef.current) {
edgeRef.current.attributes.set('style', 'dashed');
}
console.log('Digraph nodes:', digraphRef.current?.nodes.length);
console.log('Digraph edges:', digraphRef.current?.edges.length);
console.log('Graph nodes:', graphRef.current?.nodes.length);
console.log('Graph edges:', graphRef.current?.edges.length);
};
return (
Render Graph
);
}
```
## Contributors 👥
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors)
specification. Contributions of any kind welcome!
## License ⚖️
This software is released under the MIT License, see [LICENSE](https://github.com/ts-graphviz/ts-graphviz/blob/main/LICENSE).
