Sticky list headers

[nikita-kart]

Proposed Changes

Related to bpmn-io/bpmn-js-properties-panel#1103

These changes allow list headers to become sticky to the properties panel when scrolled past. This is particularly useful when managing long lists of values, as it eliminates the need to constantly scroll back up to add new elements to a list or map. It is especially convenient for maps where each entry contains multiple fields making scrolling distance quite long.

Additionally, there is the ability to set nesting levels for headers, which is useful when working with multiple nested lists or maps. This value is used to set z-index and top margin for the sticky position and to properly detect stickiness with useStickyIntersectionObserver hook.

A value of 1 means that the list is at the first nesting level within its group section. If this property is not set, the header will behave as before.

How it looks like

Checklist

To ensure you provided everything we need to look at your PR:

• Brief textual description of the changes present
• Visual demo attached
• Steps to try out present, i.e. using the @bpmn-io/sr tool
• Related issue linked via Closes {LINK_TO_ISSUE} or Related to {LINK_TO_ISSUE}

[CLAassistant]

All committers have signed the CLA.

[jarekdanielak]

Great contribution! 👏

I think we could consider making stickiness the default behavior for the list headers, like it is for the group headers. What do you think @barmac?

Let's have our designer take a look too. cc. @lmbateman (Task > Inputs > Assignment type > Map > Map entries)

I prepared a test branch in bpmn-js-properties-panel where it's enabled for map entries:

npx @bpmn-io/sr -c="npm run start:platform" -l="nikita-kart/properties-panel#sticky-list-headers" bpmn-io/bpmn-js-properties-panel#header-nesting

I'll continue with a proper code review when we decide if we want to make it the new default.

[jarekdanielak]

position: sticky is now widely available for all major browsers. I think we can skip it.

[nikita-kart]

Thanks for pointing that out, I removed -webkit-sticky

[lmbateman]

Very nice! I can't think of much to say, except let's try adding a left border and see how it looks. I don't think we need a background, although we can always try it out.

I did notice that I can't seem to get subheaders under Execution Listeners. Will this be extended to all multi-level sections?

[barmac]

I think we could consider making stickiness the default behavior for the list headers, like it is for the group headers. What do you think @barmac?

I agree. It works great for the groups, so there's no reason to not make it the default for lists too.

[nikita-kart]

Thanks for feedback!

let's try adding a left border and see how it looks

I tried that, here's the result:

Without changing left margin of the header text it looks kinda strange to me, so I also tried to set additional margin when it becomes sticky:

Looks better but there is this "jump" now when the header moves to the right a bit

I did notice that I can't seem to get subheaders under Execution Listeners. Will this be extended to all multi-level sections?

I need a little clarification here. Are you talking about every foldable element in panel and not just lists and maps? I did not tried to that, but I might look into it when I'll have a moment

[lmbateman]

Looks better but there is this "jump" now when the header moves to the right a bit

Thanks for trying this out! I'm guessing it would not be easy to move the left border to the left a few pixels to prevent the jump. If that's correct, then we should probably stay with the version without the left border.

[jarekdanielak]

See my proposal for a simplified solution (1ecf52e), that:

• makes all lists and maps headers sticky by default
• doesn't add logic to useStickyIntersectionObserver
• doesn't require changes in bpmn-js-properties-panel

It misses the edge case where the nested header is briefly hidden behind the main header. However, this isn’t noticeable during normal use of the properties panel, so I don’t think it’s worth adding extra logic to the Intersection Observer just to handle it.

@barmac let's have a final look & merge.

[barmac]

It misses the edge case where the nested header is briefly hidden behind the main header. However, this isn’t noticeable during normal use of the properties panel, so I don’t think it’s worth adding extra logic to the Intersection Observer just to handle it.

Could you please share a screencast?

[barmac]

Is this what you meant?

Screen.Recording.2025-06-12.at.15.20.46.mov

[barmac]

This problem can be solved if we lower the z-index of the nested header.

Screen.Recording.2025-06-12.at.15.26.31.mov

[nikku]

I tried this out locally, via npm run start:platform in the bpmn-js-properties-panel project.

Overall it works correctly, and is a simple solution. However across list items and now map headers being sticky I miss the actual elements to be sticky, too. The fact that I am in the inputs section is now preserved, the fact that I'm within an input's map section is preserved. What I don't know is what input I'm currently manipulating.

[barmac]

Indeed, we'd need to implement sticky Collapsible headers to achieve what you propose @nikku. That should close the story.