Adding new custom element to the pallete

Hi there , I am trying to add a new custom element to the pallete using this icon

I had a look at the custom element example but not entirely sure how to bring that into my existing project.

What would I have to change and where within my project to be able to add the mentioned icon?

Any help/insight is welcomed.

What about the example is unclear?


I’m not sure what @Paddy_B wants to implement but I also want to add some elements in the pallete and I agree that the Custom element example is unclear @philippfromme.

In this example the circle and the triangle are added in the pallete and when you drag them in the canvas they are drawn on the fly. I, and probably @Paddy_B, want to add elements with predefined icon, not to draw figures. Also, the circle and the triangle are only for visual purposes with no semantics (no menu item), I guess because they are not linked to any business object.
But in that case, how to add/edit a business object?

There’s also the Nyan example but again in that example the “cat” simply replaces the “Service Task”. What if I want the “cat” to represent a new element, not the existing ones?

@philippfromme, I see a lot of posts from the community users asking how to add custom elements. For you the “Custom element” example may be easy and clear, but could you explain a bit the logic behind? Personally I’m confused where to make changes. Shall I copy the “Custom element” example and edit there files like “CustomRenderer.js”? If I want to make any changes at the “diagram-js”, which files are the ones that are normally customized? How is the relation of the visual part and the business objects? Any good documentation?

Thanks a lot in advance!


Hey @kontrag,

thanks for the feedback. I agree with you that we need more documentation. That would also make our lifes easier because we get asked the same questions again and again, same goes for anything related to the properties panel. That’s not your fault. I’m going to address this and look into how we can improve the examples and maybe even remove bpmn-js-nyan since it seems to cause a lot of confusion instead of actually helping people.

1 Like

The custom element example already states which components are added to the BPMN modeler. It gives a little bit explanation about the responsibility of each component, too. For instance, the linked CustomPalette is responsible for providing the actual palette entry to drag elements out from.

Concrete questions or pointers of what you are struggling with would help us to improve the example. Adding all features to it, including all sorts of menu actions would probably bloat up the example beyond a point where no one will be able to understand it anymore.

What’s interesting in order to improve these examples is what did you understand / what did work and what is still unclear / did not work. Based on these concrete pointers we can go ahead and carry out improvements.

It is important, too that we understand what you are trying to achieve. This is especially relevant as there is no single answer to the question how to add custom elements. Just a few variants here:

  • auto generated, annotations, not movable by users
  • additional model elements freely model on the canvas

In order to better understand the example I suggest trying it out and, removing individual components from this module. This way you can learn how the presence of each component influences the example.