This page introduces maxGraph, a TypeScript graph visualization library. It covers the library's purpose, capabilities, repository structure, distribution model, and architectural philosophy. For detailed architectural information, see Architecture Overview. For installation and usage instructions, see Getting Started.
maxGraph is a fully client-side TypeScript library for creating interactive graph visualizations using SVG and HTML rendering. The library enables applications to display and manipulate diagrams consisting of vertices (nodes represented by shapes) and edges (connections between vertices).
The Graph class serves as the primary interface for applications. It orchestrates a plugin-based architecture where components like SelectionHandler, ConnectionHandler, and CellEditorHandler provide opt-in functionality. The underlying GraphDataModel maintains the graph structure independently of visualization, while GraphView and CellRenderer handle the transformation to SVG DOM elements.
Sources: packages/core/README.md4-12 README.md8-16
maxGraph provides functionality for interactive diagramming applications:
| Category | Features |
|---|---|
| Graph Elements | Vertices, edges, groups (hierarchical structure) |
| Interaction | Cell selection, drag-and-drop, resizing, rotation, in-place editing |
| Styling | Object-based styles (CellStyle), stylesheets, named styles, shape registry |
| Rendering | SVG output via SvgCanvas2D, shape primitives, custom shapes |
| Layout | Edge routing algorithms (orthogonal, manhattan, entity-relation) |
| Serialization | XML import/export via ModelXmlSerializer and Codec system |
| Extension | Plugin architecture, custom shapes, custom perimeters, custom edge styles |
The library targets applications requiring precise control over graph behavior, such as diagramming tools, workflow designers, and network visualizers. Unlike off-the-shelf packages, maxGraph emphasizes customization and integration with Graph Theory concepts.
Sources: README.md12-15 packages/core/package.json10-16
maxGraph uses an npm workspaces-based monorepo. The @maxgraph/core package is the primary deliverable, published to the npm registry. Supporting packages provide examples, documentation, and testing infrastructure.
The workspace configuration in package-lock.json9-10 declares ./packages/* as workspace members. Example packages demonstrate integration patterns: tree-shaking with selected features, usage without default plugins, and headless Node.js execution.
Sources: package-lock.json1-11 README.md136-157 packages/website/docs/demo-and-examples.md17-41
The @maxgraph/core package is published to the npm registry in dual ESM and CommonJS formats with TypeScript declarations. The package structure accommodates both module systems:
| Export Path | Format | Description |
|---|---|---|
. (default) | ESM: lib/esm/index.jsCJS: lib/cjs/index.js | Main entry points with type definitions |
./css/* | Static | Stylesheets for graph rendering |
./images/* | Static | Default shape and marker images |
./i18n/* | Static | Translation resources |
./xsd/* | Static | XML schema definitions |
Installation via npm package managers:
Compatibility requirements:
The package includes a LICENSE file (Apache 2.0) and publishes with OIDC provenance for supply chain security.
Sources: packages/core/package.json1-77 README.md44-69 packages/website/docs/getting-started.mdx19-46
maxGraph is a fork of mxGraph which reached end-of-life on November 9, 2020. The fork was created on November 12, 2020, with the goal of maintaining a working version and modernizing the codebase. The project was renamed from "mxGraph fork" to "maxGraph" on June 2, 2021, due to licensing considerations.
The modernization from mxGraph 4.2.2 included:
| Change | Rationale |
|---|---|
| TypeScript migration | Type safety, IDE integration, based on typed-mxgraph |
| ES2020 target | Removed ES9 and IE-specific code |
| Immutable constants | constants namespace replaces mutable mxConstants |
| Object-based styles | CellStyle objects replace string parsing |
| Plugin architecture | Opt-in handlers replace direct properties |
| Explicit registration | Codecs and shapes require registration for tree-shaking |
| npm package maintenance | Active releases on npm registry |
The CHANGELOG.md documents breaking changes across versions. The migration guide provides API mappings for mxGraph users.
Sources: README.md176-200 CHANGELOG.md437-447
maxGraph adopts several architectural principles that distinguish it from the legacy mxGraph:
The entire codebase is written in TypeScript, providing compile-time type checking and enabling IDE features like autocomplete and inline documentation. Type definitions in packages/core/package.json20 declare both ESM and CJS types, ensuring compatibility across module systems.
The Graph class uses a plugin system where functionality is opt-in. Handlers like SelectionHandler and ConnectionHandler implement the GraphPlugin interface and are registered in the Graph constructor. Applications retrieve plugins via graph.getPlugin<T>(name), which returns undefined if the plugin is not registered. This enables tree-shaking: applications that don't use selection features don't include SelectionHandler in their bundle.
Global configuration uses read-only namespaces and configuration objects:
| Legacy (mxGraph) | Modern (maxGraph) |
|---|---|
mxConstants.DEFAULT_FONTSIZE (mutable) | constants.DEFAULT_FONTSIZE (immutable) |
EdgeStyle.MANHATTAN_STEP (static property) | ManhattanConnectorConfig.step (runtime config) |
Client.language (static property) | TranslationsConfig.getLanguage() (accessor) |
This pattern prevents accidental modification of defaults and supports runtime reconfiguration.
Shapes, edge styles, perimeters, and codecs require explicit registration:
This reduces bundle size by excluding unused features. The Graph class provides defaults, BaseGraph requires manual setup for maximum control.
The Client class detects browser capabilities but no longer includes IE-specific workarounds. The IS_SVG, IS_TOUCH, and IS_POINTER flags inform rendering decisions across modern browsers.
Sources: packages/core/src/Client.ts1-216 CHANGELOG.md343-350 README.md23-26
maxGraph supports modern browsers with SVG capabilities:
Client.IS_TOUCH flag packages/core/src/Client.ts194-195Client.IS_POINTER flag packages/core/src/Client.ts200-204Platform detection flags:
Client.IS_WIN, Client.IS_MAC, Client.IS_CHROMEOS packages/core/src/Client.ts176-188Client.IS_ANDROID, Client.IS_IOS packages/core/src/Client.ts105-113The library uses SVG for rendering (checked via Client.IS_SVG packages/core/src/Client.ts158-160), requiring browsers that support SVGForeignObjectElement for advanced features.
Sources: README.md30-32 packages/core/src/Client.ts36-213
The repository uses GitHub Actions for CI/CD:
Release process is documented in packages/website/docs/development/release.md Version updates are handled by scripts/update-versions.mjs which modifies package-lock.json35 packages/core/package.json5 and packages/core/src/util/Constants.ts (VERSION constant).
Contributing guidelines are in CONTRIBUTING.md Key requirements:
Sources: packages/website/docs/development/release.md1-114 CONTRIBUTING.md1-335 scripts/update-versions.mjs1-67
The published package includes:
@maxgraph/core/
├── lib/ # Compiled outputs
│ ├── esm/ # ES modules + .d.ts
│ └── cjs/ # CommonJS + .d.ts
├── css/ # Stylesheets
├── images/ # Default icons/markers
├── i18n/ # Translation files
├── xsd/ # XML schemas
├── package.json # Package manifest
└── LICENSE # Apache 2.0
Import patterns:
For Node.js headless usage, jsdom provides browser globals. The js-example-nodejs demonstrates both ESM and CJS integration:
Sources: packages/core/package.json21-44 packages/js-example-nodejs/README.md1-19 packages/js-example-nodejs/src/index.mjs1-27
For installation and basic usage:
For examples and integration patterns:
For migration from mxGraph:
Sources: README.md71-127 packages/website/docs/getting-started.mdx1-216 packages/website/docs/demo-and-examples.md1-43
The project follows semantic versioning and maintains an active development cycle with regular releases. The latest version is 0.22.0 released December 11, 2024.
Sources: README.md166-173 packages/website/docs/getting-started.mdx209-215 CHANGELOG.md16-22
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.