News from the project

Overlays and more Modeling

Published by Nico Rehwaldt on Wednesday, 06 August 2014.


The new version of bpmn-js released today adds an overlay API and many enhancements to process modeling. The overlay API allows you to decorate BPMN 2.0 diagrams with additional data (think of comments or process state). The modeler can now create more BPMN 2.0 elements, moves them and performs automatic connection cropping.

Todays release of bpmn-js marks another big step towards a process modeler. We can now model intermediate events, text annotations and gateways. See yourself:

Create your own process on and try out the new modeling features yourself.

Drag elements

On top of an extended modeling palette we added the ability to move elements. This comes with some handy gimmics such as relayouting incoming and outgoing connections as well as automatic connection cropping.

All changes can be undone and exports to valid BPMN 2.0 XML.


Overlays are pieces of HTML that you can attach to BPMN elements. They can be used to implement a wide range of features such as visual process statistics, comments or even process debug controls.

Starting from this version you will be able to decorate your BPMN 2.0 diagrams with overlays using bpmn-js. The library will take care of all the positioning and scaling of overlays for you, so you can focus on what you want to put on top of your process diagrams.

The following screencast shows overlays that display each elements id in action during modeling and process navigation:

A process element overlay is plain html and can be attached to a process element using only a few lines of code:

// get overlays service
var overlays = bpmnViewer.get('overlays');

// add overlay to StartEvent_1
overlays.add('StartEvent_1', {
  html: '<div>ID: StartEvent_1</div>',
  position: {
    right: 0,
    bottom: 0

Check out the overlays example project to get started with overlays on the bpmn-js viewer.

New quick start project

We have created a quick start áka seed project that should make it a lot easier for you to try out our BPMN 2.0 viewer. Simply download it, open the contained index.html and you are up and running with bpmn-js.

Did we tell you, we got a new getting started section on our site, too?

Wrap up

We are curious to learn about different use cases for our new overlay API. If you created something, tell us about it on mastodon. Make sure to report bugs and other issues in our bug tracker, too.

For now, happy modeling on

PS: The new version of bpmn-js is available via npm and bower.

Are you passionate about JavaScript, modeling, and the web?
Join Camunda and build modeling tools people heart.