bpmn-visualization
is a TypeScript library for visualizing process execution data on BPMN diagrams, with simplicity.
Based on the customization capability, it provides a set of diagram visualization features that includes additional display options for execution data (highlighting of some elements, adding customizable overlays, and more) as well as personalized interactive capabilities (mouse hover, click, and more).
We hope it will help you to create applications for process visualization and analysis 🙂
Please check the ⏩ live environment.
You will find there basic usage as well as detailed examples showing possible rendering customizations.
bpmn-visualization
is actively developed and maintained.
Before the release of version 1.0.0
, there may be some breaking changes. We avoid these as much as possible, and carefully document them in the release notes.
As far as possible, we maintain compatibility for some minor versions.
- ✨ True opensource license without watermark display
- ⚡️ Strong identity: the only BPMN viewer with a woman icon in the User Tasks
- 🎸 Fully documented and with a lot of integration examples
- 👓 Highly customizable rendering in a simple way
- 🔥 TypeScript support
- 🎯 Battle tested: high test coverage, thousands of tests, including tests on all supported browsers for Linux, macOS and Windows
Already available features:
- Supported BPMN Elements.
- Navigate through the BPMN diagram
- Display execution data with interactive capabilities
🔥 Some add-on features are available through a dedicated package: ⏩ bpmn-visualization add-ons
Planned new features:
- Additional BPMN styling capabilities
- Library extension points
✔️ | ✔️ | ✔️ | ✔️ |
Notes:
- Chromium based browsers should work (automatic tests are run with Chromium canary releases). In particular, the following
desktop browsers are known working with
[email protected]
:- Brave 1.66.118
- Chromium 125.0.6422.147
- Opera 110.0.5130.66
- Support Chromium Edge but not Legacy Edge
- The library may work with the other browsers. They must at least support ES2015.
The library is available from NPM.
We support various module formats such as:
- ESM:
dist/bpmn-visualization.esm.js
- IIFE:
dist/bpmn-visualization.js
and its minified companiondist/bpmn-visualization.min.js
Install bpmn-visualization
:
npm i bpmn-visualization
Then use this snippet to load your BPMN diagram in a page:
import { BpmnVisualization } from 'bpmn-visualization';
// initialize `bpmn-visualization` and load the BPMN diagram
// 'bpmn-container' is the id of the HTMLElement that renders the BPMN Diagram
const bpmnVisualization = new BpmnVisualization({ container: 'bpmn-container' });
let bpmnContent; // your BPMN 2.0 XML content
bpmnVisualization.load(bpmnContent);
You can set the BPMN content using one of the following ways:
- Copy/Paste directly the XML content in a variable
- Load it from an url, like this example
- Load from your computer, like the demo example
The bpmn-visualization
npm package includes type definitions, so the integration works out of the box in TypeScript projects.
bpmn-visualization
requires TypeScript 4.0 or greater. Past versions had the following requirements:
- 0.21.0 to 0.27.1: TypeScript 4.5
- 0.17.1 to 0.20.1: TypeScript 4.3
ℹ️ If you are looking for examples of projects integrating bpmn-visualization
with TypeScript, see the bpmn-visualization-examples
repository.
NOTE
Prior version 0.27.0, bpmn-visualization
required extra configuration for TypeScript projects as explained in the v0.26.2 README.
In the HTML page:
- Load
bpmn-visualization
(replace{version}
by the recent version) - Define the container that displays the BPMN diagram, here bpmn-container
- Load your BPMN diagram in a page
<script src="https://cdn.jsdelivr.net/npm/bpmn-visualization@{version}/dist/bpmn-visualization.min.js"></script>
...
<div id="bpmn-container"></div>
...
<script>
// initialize `bpmn-visualization` and load the BPMN diagram
// 'bpmn-container' is the id of the HTMLElement that renders the BPMN Diagram
const bpmnVisualization = new bpmnvisu.BpmnVisualization({ container: 'bpmn-container'});
let bpmnContent; // your BPMN 2.0 XML content
bpmnVisualization.load(bpmnContent);
</script>
The User documentation (with the feature list & the public API) is available in the documentation site.
💡 Want to know more about bpmn-visualization
usage and extensibility? Have a look at the
⏩ live examples site.
For more technical details and how-to, go to the bpmn-visualization-examples
repository.
To contribute to bpmn-visualization
, fork and clone this repository locally and commit your code on a separate branch.
Please write tests for your code before opening a pull-request:
npm test # run all tests
You can find more detail in our Contributing guide. Participation in this open source project is subject to a Code of Conduct.
✨ A BIG thanks to all our contributors 🙂
bpmn-visualization
is released under the Apache 2.0 license.
Copyright © 2020-present, Bonitasoft S.A.
Some BPMN icons used by bpmn-visualization
are derived from existing projects. See the BPMN Support documentation
for more details:
- draw.io (Apache-2.0)
- flaticon (freepikcompany license)
- noun project (mainly Creative Commons CCBY 3.0)
statically.io (demo and examples live environments)
surge.sh (demo and documentation preview environments)