[Feature Request](ui5-side-navigation): fire event when group/item is expanded or collapsed

[JohannesDoberer]

Feature Request Description

When a ui5-side-navigation-group (or item with sub-items) is expanded or collapsed, no event is fired. The _toggle() method in SideNavigationGroup simply sets this.expanded = !this.expanded without calling fireDecoratorEvent().

The only event ui5-side-navigation currently fires is selection-change (when an item is selected). There is no way to be notified about expand/collapse state changes.

We need to persist the expanded/collapsed state of navigation groups (e.g. to localStorage) so that the user's preferred navigation layout survives page reloads or route changes. Without an event, the only workaround is a MutationObserver watching the expanded attribute on all child elements — which works but is fragile and non-idiomatic for a web component:

const observer = new MutationObserver((mutations) => {
  mutations.forEach((mutation) => {
    if (mutation.type === 'attributes') {
      const target = mutation.target;
      if (target.hasAttribute('expanded')) {
        // persist state
      }
    }
  });
});

observer.observe(sideNavigation, {
  attributes: true,
  subtree: true,
  attributeFilter: ['expanded'],
});

This workaround relies on the expanded attribute being reflected to the DOM as an HTML attribute on the child elements. If UI5 internally refactors to use CSS classes, shadow DOM state, or stops reflecting the attribute, the observer silently breaks without warning.

Additionally, ui5-tree already fires an item-toggle event with { item } when a tree node is expanded/collapsed. The side navigation should behave consistently — users expect the same interaction patterns across UI5 components.

Proposed Solution

An event on ui5-side-navigation itself (similar to how selection-change bubbles up from items):

Event: expand-change
detail: { item: HTMLElement, expanded: boolean, programmatic: boolean }

This would fire whenever a group or item toggles its expanded state — whether triggered by click, keyboard (arrow keys, +/−), or programmatically.

The event should fire both on user interaction and when expanded is set programmatically. Our use case requires tracking all expand/collapse state changes regardless of trigger — for example, when navigation groups are expanded programmatically during route changes, the persisted state in localStorage must stay in sync. A flag like programmatic: boolean in the event detail could help consumers distinguish the source if needed, but firing in both cases is essential.

Proposed Alternatives

No response

Organization

luigi-project

Additional Context

No response

Priority

Medium

Privacy Policy

• I’m not disclosing any internal or sensitive information.

[kgogov]

Verified — this is a valid gap. Confirmed against source, the public API, and live runtime:

• SideNavigationGroup._toggle() and SideNavigationItem._toggle() both flip expanded with no event fired (SideNavigationGroup.ts:188, SideNavigationItem.ts:382). Keyboard (arrows, +/−), click, and programmatic expanded changes are all silent.
• ui5-side-navigation only fires selection-change and item-click — nothing for expand/collapse.
• The MutationObserver workaround does work today (expanded reflects as a DOM attribute), but relying on that is fragile, as noted.

A few decisions needed before implementation:

1. Event name. The issue proposes expand-change, but also asks for consistency with ui5-tree, which uses item-toggle with { item }. Recommend item-toggle for parity (and it sits naturally next to the existing item-click).
2. Programmatic firing. The request needs the event to fire on programmatic expanded changes too. Note this goes beyond the Tree precedent — Tree's item-toggle does not fire on a programmatic toggle(). This is the trickiest part (property setter vs. user interaction) and the programmatic: boolean flag in the detail is the suggested way to distinguish.
3. Cancelable? Tree's item-toggle is cancelable (enables lazy-loading child nodes). Worth deciding if we want the same here.

Scope: two components toggle independently — SideNavigationGroup and SideNavigationItem (items with sub-items) — plus the collapsed-mode popover path. All three need coverage.

[kgogov]

Hello @UI5/ui5-team-ctr-rod,

Could you please take a look at the following feature request?

Regards,
Konstantin

[GerganaKremenska]

Hello @olannyv,

Please create a backlog item, so we cna review the request.

Best Regards,
Gergana