bpmn-js-properties-panel

July 29, 2026 · View on GitHub

A properties panel extension for bpmn-js that adds the ability to edit technical properties (generic and Camunda).

Features

The properties panel allows users to edit invisible BPMN properties in a convenient way.

Some of the features are:

Edit element ids, multi-instance details and more
Edit execution related Camunda 7 and Camunda 8 properties
Redo and undo (plugs into the bpmn-js editing cycle)

Usage

Provide two HTML elements, one for the properties panel and one for the BPMN diagram:

<div class="modeler">
  <div id="canvas"></div>
  <div id="properties"></div>
</div>

Bootstrap bpmn-js with the properties panel and a properties provider:

import BpmnModeler from 'bpmn-js/lib/Modeler';
import {
  BpmnPropertiesPanelModule,
  BpmnPropertiesProviderModule,
} from 'bpmn-js-properties-panel';

const modeler = new BpmnModeler({
  container: '#canvas',
  propertiesPanel: {
    parent: '#properties'
  },
  additionalModules: [
    BpmnPropertiesPanelModule,
    BpmnPropertiesProviderModule
  ]
});

Styling

For proper styling include the necessary stylesheets:

<link rel="stylesheet" href="https://unpkg.com/@bpmn-io/properties-panel/dist/assets/properties-panel.css">

Dynamic Attach/Detach

You may attach or detach the properties panel dynamically to any element on the page, too:

const propertiesPanel = bpmnJS.get('propertiesPanel');

// detach the panel
propertiesPanel.detach();

// attach it to some other element
propertiesPanel.attachTo('#other-properties');

Edit Camunda Properties

To edit Camunda properties, you have to use a moddle extension so bpmn-js is can read and write Camunda properties and use a provider so these properties are shown in the properties panel.

For example, to edit Camunda 8 properties, use the Camunda 8 moddle extension and the Camunda 8 provider. Additionally, you should use behaviors specific to Camunda 8 to ensure parts of the model that are specific to Camunda 8 are maintained correctly.

import BpmnModeler from 'bpmn-js/lib/Modeler';
import {
  BpmnPropertiesPanelModule,
  BpmnPropertiesProviderModule,
  ZeebePropertiesProviderModule // Camunda 8 provider
} from 'bpmn-js-properties-panel';

// Camunda 8 moddle extension
import zeebeModdle from 'zeebe-bpmn-moddle/resources/zeebe';

// Camunda 8 behaviors
import ZeebeBehaviorsModule from 'camunda-bpmn-js-behaviors/lib/camunda-cloud';

const modeler = new BpmnModeler({
  container: '#canvas',
  propertiesPanel: {
    parent: '#properties'
  },
  additionalModules: [
    BpmnPropertiesPanelModule,
    BpmnPropertiesProviderModule,
    ZeebePropertiesProviderModule,
    ZeebeBehaviorsModule
  ],
  moddleExtensions: {
    zeebe: zeebeModdle
  }
});

API

`BpmnPropertiesPanelRenderer#attachTo(container: HTMLElement, headerContainer?: HTMLElement) => void`

Attach the properties panel to a parent node.

const propertiesPanel = modeler.get('propertiesPanel');

propertiesPanel.attachTo('#other-properties');

// or attach the panel body and header to different containers
propertiesPanel.attachTo('#properties', '#panel-header');

`BpmnPropertiesPanelRenderer#detach() => void`

Detach the properties panel from its parent node.

const propertiesPanel = modeler.get('propertiesPanel');

propertiesPanel.detach();

`BpmnPropertiesPanelRenderer#registerProvider(priority: Number, provider: PropertiesProvider) => void`

class ExamplePropertiesProvider {
  constructor(propertiesPanel) {
    propertiesPanel.registerProvider(500, this);
  }

  getGroups(element) {
    return (groups) => {

      // add, modify or remove groups
      // ...

      return groups;
    };
  }
}

ExamplePropertiesProvider.$inject = [ 'propertiesPanel' ];

`BpmnPropertiesPanelRenderer#getEntryId(element: djs.model.Base, path: Array<string|number>) => string|null`

Resolve the id of the entry that edits the given moddle property path, relative to the element's business object. Providers may implement getEntryId(element, path) to resolve paths for the groups they contribute; they are asked in reverse render order, so a provider whose groups render last (e.g. one registered with a low priority to override others) is asked first.

const propertiesPanel = modeler.get('propertiesPanel');

const entryId = propertiesPanel.getEntryId(element, [
  'extensionElements', 'values', 0, 'inputParameters', 1, 'source'
]);
// 'ServiceTask_1-input-1-source'

Additional Resources

Development

Prepare the project by installing all dependencies:

npm install

Then, depending on your use-case, you may run any of the following commands:

# build the library and run all tests
npm run all

# spin up a single local modeler instance
npm start

# run the full development setup
npm run dev

License

MIT