Skip to content

DgrmJS is a JavaScript library for creating SVG flow diagrams. The main goal of the library is to set up workflows in BPM (Business Process Management) systems. Works on desktop and mobile, has no dependency, 3.5 KB gzipped.

License

AlexeyBoiko/DgrmJS

main
Switch branches/tags
Code

DgrmJS

NPM

DgrmJS is a JavaScript library for creating SVG flow diagram editors.
The main goal of the library is to set up workflows in BPM (Business Process Management) systems.

  • Works on desktop and mobile
  • Has no dependency
  • 3.5 KB gzipped

Demo: diagram editor dgrm.net.

diagram

Articles:
JavaScript SVG diagram editor 6.5 times smaller than Bootstrap
JavaScript diagram editor that renders diagrams from PNG images (open source)
JavaScript text editor for SVG

Main idea

  • Allow developers to use standard SVG objects and features to declaratively create shapes that will be used in the diagram.
    To create shape, developers should add special data- attributes to standard SVG markup. So any svg images can be used as a shape in a diagram.
  • DgrmJS dispatch events, like ‘shape is selected’ or ‘shape is connecting to another shape’.
    Developers can use these events to implement their own logic, for example, make a JSON description of the workflow.

Apache-2.0 license

Free for any type of use. Including commercial projects.

How to use

See a minimalistic example - GitHub repository: DgrmJS Example.

Install

From npm:

npm i dgrm

Simple shape

This is a circle shape:

<svg id="diagram" style="touch-action: none;">
	<defs>
		<!-- shape template 'circle' -->
		<g data-templ="circle">
			<circle ... />
			<!-- inner named element,
			we can use 'data-key' value as a key
			in shapeAdd(...) method -->
			<text data-key="text"></text>
		</g>
	</defs>
	<g data-key="canvas"></g>
</svg>
<script type="module">
	import { svgDiagramCreate } from './diagram/svg-presenter/svg-diagram-factory.js';

	const diagram = svgDiagramCreate(document.getElementById('diagram'))

	// add shape to canvas
	diagram.shapeAdd({
		// template name
		// (value of the 'data-templ' attribute)
		templateKey: 'circle',
		position: { x: 120, y: 120 },
		props: {
			// inner svg element with 'data-key=text'
			// will get 'textContent' value 'Title'
			text: { textContent: 'Title' }
		}
	});
</script>

diagram.shapeAdd method add to canvas shape:

  • created by template with name "circle"
  • to position at point 120, 120
  • props set
    • textContent of the inner element with data-key="text" to "Title"

This way you can set any attribute of any shape object.

Result is a draggable circle with "Title" text:

draggable shape

Add "out connectors" to shape

"Out connector" is an element from which you can draw out a connecting line.
Add data-connect="out" to mark element as a out connector:

<g data-templ="circle">
    <circle ... />
    <text data-key="text"></text>
 
    <!--
        out connector
        data-connect-point - point into shape where connector line starts
        data-connect-dir - direction of connector line
    -->
    <circle
        data-connect="out"
        data-connect-point="60,0"
        data-connect-dir="right" ...>
    </circle>
</g>

draggable shape

Add "in connectors" to shape

"In connector" is an element where you can connect a connection line to a shape.

<g data-templ="circle">
    <circle ... />
    <text data-key="text"></text>
 
    <!--
        out connector
        data-connect-point - point into shape where connector line starts
        data-connect-dir - direction of connector line
    -->
    <circle
        data-connect="out"
        data-connect-point="60,0"
        data-connect-dir="right" ...>
    </circle>
 
    <!--
        in connector
    -->
    <circle
        data-connect="in"
        data-connect-point="-60,0"
        data-connect-dir="left" ...>
    </circle>
</g>

draggable shape

Events

In this example:

  • we subscribe to the select event
  • update title of the selected shape
<svg id="diagram" style="touch-action: none;">
    <defs>
        <!-- shape template 'circle' -->
        <g data-templ="circle">
            <circle ... />
            <!-- inner named element,
                we can use 'data-key' value as a key
                in shapeAdd(...) method -->
            <text data-key="text"></text>
 
            <!-- connectors -->
            <circle data-connect="out" ...></circle>
            <circle data-connect="in" ...></circle>
        </g>
    </defs>
    <g data-key="canvas"></g>
</svg>
<script type="module">
    import { svgDiagramCreate } from './diagram/svg-presenter/svg-diagram-factory.js';
 
    const diagram = svgDiagramCreate(document.getElementById('diagram'))
        // subscribe to 'select' event
        .on('select', evt => {
 
            // update selected shape
            evt.detail.target.update({
                props: {
                    text: { textContent: 'New title' }
                }
            });
 
        });
 
    // add shape to canvas
    diagram.shapeAdd({
        templateKey: 'circle',
        position: { x: 120, y: 120 },
        props: {
            text: { textContent: 'Title' }
        }
    });
</script>

draggable shape

Project structure

Diagram Engine (src/diagram folder)

src/diagram folder contains a diagram engine that can be used independently of other project files.
This diagram engine contains all main features (all you need to implement diagram editor in your project):

  • creating shapes with svg templates
  • drag'n'drop
  • connection of shapes
  • diagram events

Source code in src/diagram folder is under the MIT License.

Diagram Extensions (src/diagram-extensions folder)

src/diagram-extensions folder contains additional features, like:

  • export/import to/from png/svg
  • text editor
  • shape editor panel
  • and other

App (src/app folder)

src/app folder contains diagram builder dgrm.net.

Documentation

Soon

About

DgrmJS is a JavaScript library for creating SVG flow diagrams. The main goal of the library is to set up workflows in BPM (Business Process Management) systems. Works on desktop and mobile, has no dependency, 3.5 KB gzipped.

Topics

Resources

License

Stars

Watchers

Forks