maxGraph

maxGraph is a TypeScript library which can display and allow interaction with vector diagrams. At a high level, it provides:

• Nodes, also known as vertices which are typically represented by shapes like rectangles.
• Edges which can be lines and arrows which normally point between one node and another.

It provides many of the diagramming features which would be expected by a piece of presentation software like Microsoft® PowerPoint™ or LibreOffice® Impress such as being able to resize, move or rotate nodes, but has a stronger focus on automatic layout algorithms and applications of Graph Theory. It is suited towards software which requires finer-grained customization of functionality than off-the-shelf packages.

The maxGraph library uses no third-party software, it requires no plugins and can be integrated in virtually any framework (it's vanilla JS).

maxGraph is the successor of mxGraph which is now end of life. At first, it provides the same features as mxGraph and adds

• TypeScript support
• maintained npm package
• modern modular, tree shakable, version of mxGraph to reduce the whole package size

New features will follow.

Browser support

Chrome, Edge, Firefox, Safari, Chromium based browsers (Brave, Opera, ....) for mobile and desktop.

Project status

maxGraph is currently under active development, with a few adjustments still required to match the behavior of mxGraph. In the meantime, new features are also being added to enrich the library.

Please try it in your application and submit an issue if you think that something is not working.

You can also test maxGraph by running the Storybook examples.

Install

Install the latest version of maxGraph from the npm registry.

npm

npm install @maxgraph/core

pnpm

pnpm add @maxgraph/core

yarn

yarn add @maxgraph/core

maxGraph is written in TypeScript and provides type definitions for seamless integration into TypeScript applications.

Compatibility of the npm package:

• The JavaScript code conforms to the ES2020 standard and is available in both CommonJS and ES Module formats
• TypeScript integration requires TypeScript 3.8 or higher

Getting Started

Here is an example that shows how to display a rectangle connected to an orange circle.

This example assumes that

• you are building an application that includes the maxGraph dependency, and it has been installed as explained above.
• your application uses a build tool or a bundler for its packaging. Direct usage of maxGraph in a web page is not supported (for more details, see #462).
• your application includes a page that defines an element with the id graph-container.
• you're using TypeScript. For JavaScript, simply remove references to the 'type' syntax.

import {type CellStyle, Graph, InternalEvent} from '@maxgraph/core';

const container = <HTMLElement>document.getElementById('graph-container');
// Disables the built-in context menu
InternalEvent.disableContextMenu(container);

const graph = new Graph(container);
graph.setPanning(true); // Use mouse right button for panning

// Adds cells to the model in a single step
graph.batchUpdate(() => {
  const vertex01 = graph.insertVertex({
    position: [10, 10],
    size: [100, 100],
    value: 'rectangle',
  });
  const vertex02 = graph.insertVertex({
    position: [350, 90],
    size: [50, 50],
    style: {
      fillColor: 'orange',
      shape: 'ellipse',
      verticalAlign: 'top',
      verticalLabelPosition: 'bottom',
    },
    value: 'ellipse',
  });
  graph.insertEdge({
    source: vertex01,
    target: vertex02,
    value: 'edge',
    style: {
      edgeStyle: 'orthogonalEdgeStyle',
      rounded: true,
    },
  });
});

You will see something like in the following maxGraph panning demo:

Documentation

The maxGraph documentation is available on the maxGraph website.

Warning

This is a work in progress, the content will be progressively improved.

Examples

For more comprehensive examples than the “Getting started” example, here is a list of demos and examples to help you understand how to use maxGraph and integrate it into your projects.

Note that they are based on maxGraph features, which require the use of CSS and images provided in the npm package.

• the storybook stories which demonstrates various features of maxGraph.
  • The stories are currently written in JavaScript and will be progressively migrated to TypeScript.
  • A live instance is available on the maxGraph website.
• the ts-example project/application that demonstrates how to define and use custom Shapes with maxGraph. It is a vanilla TypeScript application built by Vite.
• the ts-example-jest-commonjs project that demonstrates how to run jest tests involving maxGraph with ts-jest, using CommonJS.
• the ts-example-selected-features project/application that demonstrates the same use case as in ts-example but which only loads the features and configuration required by the application for an efficient tree-shaking. It is a vanilla TypeScript application built by Vite.
• the ts-example-without-defaults project/application that demonstrates how to not use defaults plugins and style defaults (shapes, perimeters, ...). It is a vanilla TypeScript application built by Vite.
• the js-example project/application that demonstrates how to import and export the maxGraph model with XML data. It is a vanilla JavaScript application built by Webpack.
• the js-example-nodejs project that demonstrates how to use maxGraph in a headless environment with Node.js.
• the js-example-selected-features project/application that demonstrates the same use case as in ts-example but which only loads the features and configuration required by the application for an efficient tree-shaking. It is a vanilla JavaScript application built by Webpack.
• the js-example-without-defaults project/application that demonstrates how to not use defaults plugins and style defaults (shapes, perimeters, ...). It is a vanilla JavaScript application built by Webpack.
• the maxgraph-integration-examples repository which shows how to integrate maxGraph with different frameworks and build tools.

Migrating from mxGraph

maxGraph APIs are not fully compatible with mxGraph APIs. The concepts are the same, so experienced mxGraph users should be able to switch from mxGraph to maxGraph without issues.

For a complete guide, see the dedicated migration page.

Support

For usage question, please open a new discussion on GitHub. You can also use GitHub discussions for other topics like maxGraph development or to get the latest news.

For bug reports, feature requests, or other issues, please open a new issue on GitHub.

History

On 2020-11-09, the development on mxGraph stopped and mxGraph became effectively end of life.

On 2020-11-12, a fork of the mxGraph was created with a call to Contributors.

12 Nov 2020.

If you are interested in becoming a maintainer of mxGraph please comment on issue #1

Initial objectives:

• The first priority is to maintain a working version of mxGraph and its npm package
• The ambitious stretch goal is to refactor the codebase to create a modern modular, tree shakable, version of mxGraph to reduce the whole package size.

-- Colin Claverie

The project was then renamed on 2021-06-02 into maxGraph due to licensing issue.

Starting from the mxGraph 4.2.2 release, we

• moved code to ES9
• removed Internet Explorer specific code
• migrated to TypeScript, based on the work initiated in typed-mxgraph
• migrated the examples to Storybook

Development

Contributing

We welcome contributions! Please see the contributing guide for:

• Setup instructions and prerequisites
• Development workflow and commands
• Code quality standards
• Pull request process

Quick Command Reference

# Setup
nvm use                           # Use correct Node.js version
npm install                       # Install dependencies

# Development (run in parallel)
npm run dev -w packages/core      # Watch and rebuild core
npm run dev -w packages/html      # Run Storybook examples

# Building
npm run all                       # Build everything + run tests

# Testing
npm test -w packages/core         # Run tests
npm run lint                      # Check code quality

For comprehensive commands and architecture details, see CLAUDE.md.

Building the npm Package Locally

Released versions are available at npmjs.

To build locally:

# From project root
npm install

# From packages/core folder
npm pack

The packages/core folder or the generated maxgraph-core-*.tgz file can be used in your application via npm link or npm install.

Integration examples can be found in the maxgraph-integration-examples repository.

Release Process

See the release documentation for details on the release process.