JointJS Documentation

JointJS is a JavaScript/TypeScript diagramming library designed for building complex, production-scale diagramming applications. It is framework-agnostic but offers first-class, native support for React.

Common use cases include:

• Workflow & Process: Flowchart editors, BPMN modelers, and activity diagrams.
• AI Workflow Builders: Node-based AI pipeline and agent builders.
• Data Modeling: ER diagrams and database schema designers.
• Industrial/SCADA: P&ID diagrams and monitoring dashboards.
• Other domains: UML, Org charts, Energy networks, and Electronic design.

The joint-layout-directed-graph module provides automatic layout capabilities for directed graphs within JointJS.

Prerequisites: This library requires JointJS (version >= 4.0). Ensure JointJS is installed and configured in your project before using this layout module.

JointJS General Shapes is a collection of general ECMAScript / TypeScript shapes designed for use with JointJS.

Prerequisites: This library requires JointJS version 3.5 or higher. Ensure you have JointJS installed and configured before attempting to use these shapes.

JointJS is framework-agnostic. While it works with any frontend stack, specific integrations are available:

• React: Offers native components and hooks via 'JointJS for React'.
• Angular, Vue, Svelte, and Salesforce Lightning: Integration guides and examples are available in the official documentation.

To run the Eclipse Layout Kernel (ELK) Graph demo, you must first build the core JointJS library from the repository root before setting up the demo directory.

1. Build JointJS: From the repository root, install dependencies and build the project.
2. Run the Demo: Navigate to the demo directory, install its specific dependencies, and start the development server.

Since JointJS is SVG-based, you have two ways to include HTML:

1. SVG <foreignObject>: Use this for simple HTML content inside the SVG. Warning: Avoid certain CSS properties like position (except static), transform, and transition to prevent rendering issues in Safari.
2. HTML Overlay: Use the experimental useHTMLOverlay prop on the Paper component to render real HTML outside the SVG.

const renderElement = ({ width, height }) => (
  <foreignObject width={width} height={height}>
    <div style={{ background: 'lightgray' }}>
      HTML Content here
    </div
  </foreignObject>
);

<GraphProvider>
  <Paper renderElement={renderElement} />
</GraphProvider>

Overview

@joint/react is a React-first API for building interactive diagrams powered by JointJS. It wraps JointJS concepts into idiomatic React components and hooks.

Core Concepts

• Element (Node): A visual item in your diagram (e.g., a rectangle, circle, or custom shape).
• Link (Edge): A connection between two elements.
• Graph: The data model holding all elements and links.
• GraphProvider: React context provider for managing the graph state.
• Paper: The main rendering component for nodes and links.
• Ports: Named connection points on elements for precise linking.
• MeasuredNode: Utility for auto-sizing nodes based on their content.

Use @joint/vitest-plugin-mock-svg to mock SVG methods that are not implemented in JSDOM. This is necessary when running JointJS tests in a Vitest environment that uses JSDOM. To use it, import the plugin and add it to the plugins array in your vitest.config.js file.

import { defineConfig } from 'vitest/config';
import mockSVG from '@joint/vitest-plugin-mock-svg'

export default defineConfig({
  plugins: [mockSVG()],
})

For hierarchical diagrams, use devs.Atomic and devs.Coupled shapes. Both inherit from devs.Model but differ in size and color to allow for custom logic (e.g., allowing a devs.Coupled shape to embed devs.Atomic shapes).

Key methods for hierarchical workflows:

• coupled.embed(atomic): Places an atomic shape inside the coupled shape.
• coupled.fitToChildren(): Resizes the coupled shape to visually contain all its embedded elements.
• link.reparent(): Finds the most appropriate parent for a link based on its source and target elements.

To run the Custom Embedding demo locally, you must first build the core JointJS library from the repository root before launching the demo.

1. Navigate to the repository root and install dependencies and build the project:

   yarn install
   yarn run build

2. Navigate to the packages/joint-core/demo/custom-embedding/ directory.
3. Open index.html in your web browser to view the demo.

yarn install
yarn run build
# Then navigate to the demo directory and run:
open index.html