search

maxGraph / maxGraph

maxGraph is a fully client side JavaScript diagramming library
https://maxgraph.github.io/maxGraph/
Apache License 2.0
798 stars 170 forks source link
browser canvas diagram graph svg typescript

readme

maxGraph

npm version build status

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

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

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 or build the npm package locally to get the latest changes.

Install

Install the latest version of maxGraph from the npm registry.

npm

npm install @maxgraph/core

yarn

yarn add @maxgraph/core

pnpm

pnpm add @maxgraph/core

Getting Started

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

This example assumes that

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
// Gets the default parent for inserting new cells. This
// is normally the first child of the root (ie. layer 0).
const parent = graph.getDefaultParent();

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

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

maxGraph panning demo

Documentation

The maxGraph documentation is available on the maxGraph website.

[!WARNING]
This is a work in progress, the content of the original mxGraph documentation will be progressively migrated there. For more details, see #345.

Documentation partially migrated:

Documentation to be migrated:

Be aware that the maxGraph API doesn't fully match the mxGraph API (see the paragraph below about "Migrating from mxGraph").

Examples

For more complete examples than getting started,, please have a look at:

Notice that some elements produced by maxGraph require to use CSS and images provided in the npm package.

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.

TypeScript support

maxGraph is written in TypeScript and provides type definitions so maxGraph can be easily integrated into TypeScript applications.

maxGraph requires TypeScript 3.8 or greater.

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.

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

Development

Clean former mxGraph tags

Ensure you don't have the former mxGraph tags locally (see #92 fore more details):

git fetch --all --tags --prune

Setting up local development environment

NodeJS requirements:

Note: maxGraph relies on npm workspaces to build.

In the project root directory, execute

$ npm install

To watch the core package, execute:

$ npm run dev -w packages/core

To watch the examples provided as Storybook stories, execute:

$ npm run dev -w packages/html

Since both commands are in watch mode, so it's recommended to open two terminals and run them separately. When a file is saved from the core package, the html storybook will be automatically updated.

For more details about @maxgraph/html, see the README that explains the maxGraph examples.

Building the npm package locally

Reminder: the released version are available at npmjs.

Run

The packages/core folder or the generated packages/core/maxgraph-core-***.tgz file are now ready for use in your application, using npm link or npm install.

Examples of use can be found in the maxgraph-integration-examples repository.

Release

See the dedicated release page.