Skip to content
Creating custom elements in bpmn-js that live outside a BPMN 2.0 diagram.
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
app Initial commit Mar 29, 2019
docs Initial commit Mar 29, 2019
resources Initial commit Mar 29, 2019
test Initial commit Mar 29, 2019
.babelrc Initial commit Mar 29, 2019
.eslintignore Initial commit Mar 29, 2019
.gitignore Initial commit Mar 29, 2019
.npmrc Initial commit Mar 29, 2019
Gruntfile.js Initial commit Mar 29, 2019 fix(README): fix broken links May 13, 2019
karma.conf.js Initial commit Mar 29, 2019
package.json Initial commit Mar 29, 2019

⚠️ Should custom elements be serialized within the BPMN 2.0 diagram? If that is the case, this example is not what you are looking for. Checkout our 📓 custom elements guide to learn how to build custom elements in a BPMN 2.0 compatible way.

bpmn-js example: Custom Shapes

This advanced example shows how to extend bpmn-js with new shapes and connections that are not part of the BPMN 2.0 diagram / incompatible with the BPMN 2.0 standard. Consult our 📓 custom elements guide to learn how to extend the toolkit in a BPMN 2.0 compliant way.


This example extends bpmn-js, creating a custom BPMN modeler that can display and add custom shapes and connections to BPMN 2.0 diagrams.

The renderer ships with custom rules that define which modeling operations are possible on custom shapes and connections. It can import custom shapes and connections from a JSON descriptor and updates their properties during modeling.

demo application screenshot

Usage Summary

The example provides a custom modeler. After instantiation, the modeler allows you to add and get custom shapes and connections.

// add custom elements
var customElements = [
    type: "custom:triangle",
    id: "CustomTriangle_1",
    x: 300,
    y: 300
    type: "custom:connection",
    id: "CustomConnection_1",
    source: "CustomTriangle_1",
    target: "Task_1",
    waypoints: [
      // ...


// get them after modeling
customModeler.getCustomElements(); // all currently existing custom elements

The modeler ships with a module that provides the following bpmn-js extensions:

  • CustomContextPadProvider: A custom context pad that allows you to connect custom elements to BPMN elements
  • CustomElementFactory: A factory that knows about how to create BPMN and custom shapes
  • CustomOrderingProvider: A provider that ensures custom connections are always rendered on top
  • CustomPalette: A custom palette that allows you to create custom elements
  • CustomRenderer: A renderer that knows how to draw custom elements
  • CustomRules: A rule provider that defines the allowed interaction with custom elements
  • CustomUpdater: An updater that updates business data while the user interacts with the diagram

Run this Example

Fetch dependencies:

npm install

Build example and open in your browser:

npm run dev

Run tests:

npm test



You can’t perform that action at this time.