Vertical Menu

Side navigation with submenus, for deeper hierarchies than a top bar can carry.

Reach for it when you need:

• Area → line → equipment navigation down the side of a screen

Component name: VerticalMenu · Category: Navigation

In the palette: Side navigation with submenus

Properties

Any property can be bound to a tag, another component's property, or a query.

Property	Type	Default	Description
menu	array	[{"label":"Dashboard","icon":"LayoutDashboard","path":"/dash… (truncated)	—
gap	number	4	—
align	enum	top	Where the items sit along the column when the menu is taller than them. Options: top · center · bottom.
showExternalIcon	boolean	true	Mark items that leave the app with a small arrow glyph.
collapsible	boolean	false	Offer the icon-only rail (and its collapse toggle).
collapsed	boolean	false	Start collapsed to icons. Bind it to drive the rail from a tag or variable.
collapseMode	enum	tooltip	tooltip = stay a rail and show the label beside the icon; expand = widen back over the page while hovered. Options: tooltip · expand.
collapsedWidth	number	56	—
expandedWidth	number	240	Width when expanded. Independent of the widget's own box, so a narrow rail can still open wide.
showToggle	boolean	true	Render the collapse/expand button at the top of the menu.
style	style	{}	Custom CSS properties

Events

Attach event actions to these in the Event Manager.

Event	Label	Group	Payload
click	Click	Mouse	The DOM event.
dblclick	Double click	Mouse	The DOM event.
contextmenu	Right click	Mouse	The DOM event.
mouseenter	Mouse enter	Mouse	The DOM event.
mouseleave	Mouse leave	Mouse	The DOM event.

Right-click behaves differently in the Designer

contextmenu fires your configured actions at runtime only — in LiveView and in preview. On the Designer canvas the right-click is captured to open the Event Manager, so testing it there will not run your actions. Test right-click in preview.

Notes

Internal and external items

Each item declares what its path means:

• internal — a route inside the project. It is prefixed with the project slug and navigated in-app with no page reload, so a path that happens to look like a hostname (reports.2024/summary) still resolves as a route.
• external — an address outside the app. A bare host is given https:// so the browser does not resolve it against the current page, it opens in a new tab by default with rel="noopener noreferrer", and a small arrow marks it so an operator knows the click leaves the HMI.
• auto (the default) — work it out from the path. Fine for obvious cases; state it explicitly when the path is ambiguous.

Use openIn to override the tab in either direction: auto follows the kind, same keeps the operator on the current screen, new opens a second tab.

Making an item do more than navigate

An item does not have to go anywhere. Leave its path empty, give it a key, and handle Menu item click in the Event Manager. The chain receives the clicked item, so ONE handler on the menu covers every entry — each action guarded by the item it belongs to.

Every action is available (popover, panel, notification, sign in, sign out, set tag, set variable, send message, run script) because this is the same action list every other widget uses.

Worked example: Help opens a popover, Sign out signs out

1. Build the popover content. Create a view — say HelpCard — with whatever the popover should show, and give it a size (300 x 200 is a reasonable card). It needs no routing path: a popover hosts it in place.

2. Key the items. Select the menu and open the menu property. On the Help item set key to help; on the Sign out item set it to logout. Leave both path fields empty — these items run actions rather than navigating. (linkType and openIn disappear once a path is empty, which is the schema telling you the same thing.)

3. Open the handler. Right-click the menu on the canvas, choose Menu item click.

4. Add the popover. Add action → Popover. Set View to HelpCard, Anchor to This widget, and leave Side on Auto so it places itself wherever there is room.

5. Guard it to the Help item. On that action tick Only run this action when…, then:

Field	Value
source	{{item.key}} — use the picker, under Event data
operator	is
value	help

Without the guard the popover would open for every item in the menu, because the handler belongs to the whole widget rather than to one entry.

6. Add the second action. Add action → Sign out, guarded the same way with {{item.key}} is logout. Guarded actions are skipped cleanly — a skipped action records no result and raises no error, so the two never interfere.

7. Test in preview. Help opens the popover, Sign out signs out, and every other item navigates exactly as before.

Passing the clicked item into the view

Once the popover view declares params, the action shows a View Param table. Any payload field can go straight in:

Param	Value
topic	{{item.key}}
title	{{item.label}}

The full payload is {{item.key}}, {{item.label}}, {{item.path}}, {{item.href}}, {{item.external}}, {{item.newTab}}, {{item.level}}, {{item.index}} and {{item.hasSubMenu}}.

Guard on the key, never the label

Renaming "Sign out" to "Log out" would silently unwire a guard that tested the label. The key is yours and changes only when you change it.

The event fires for submenu entries too, and it fires before any navigation — so an item can both run actions and follow its path.

Parking one item at the far end

Set an item's pin to end and it renders in its own group at the far end of the menu — the bottom of a vertical menu, the right of a horizontal one — while everything else stays together at the start. This is per item, which is the point: Sign in, Sign out and Settings need to sit apart from the navigation, and a whole-menu alignment cannot say that.

Pin as many as you like; their order within the pinned group is still yours. pin applies to top-level items only — a submenu opens as a flyout, so it has no far end of its own.

Fields appear as they become relevant

linkType and openIn only show once an item has a path, and no destination field shows on an item that has children — a group expands, it never navigates. Active colours are hidden on an external item, which can never be the page you are on.

Where the items sit

Set align to top, center or bottom to park the items along the column when the menu is taller than they are.

An icon-only sidebar, step by step

This is the shape most projects want: a sidebar down the left of every screen that shrinks to a strip of icons and back. It is built from two halves — the shell reserves the space, the menu fills it — so both have to be set up, and each has one field that does the real work.

Step 1 — build the menu view

Create a view containing just the Vertical Menu, and make the menu fill it. Size the view to the width you want the sidebar to have when it is open — 240 is a good starting point. Add the items you need, and pin Sign out (or Settings) to end so it sits at the bottom.

Step 2 — give the zone the view

Open Layout Configuration and select the Left zone.

1. Enabled — on.
2. View — the menu view from step 1.
3. Behaviour — Push, so the screen content shrinks beside the sidebar rather than being covered by it.
4. Width — 240, matching the view.

Step 3 — let the zone collapse to a rail

1. Collapsible — on.
2. Collapsed width — 56.

Step 3.2 is the one that matters. Left at 0 the zone collapses to nothing: it disappears and takes the menu with it, which is why an icon sidebar seems impossible until you find this field. Any other value leaves a rail of that width and keeps rendering the view inside it — which is exactly the strip the icons need.

3. Start collapsed — on, if the screen should open with the rail.

Step 4 — decide what hovering the rail does

Back on the menu, set collapseMode:

• tooltip (default) — the rail stays a rail and the label appears beside the icon. Groups open their children as a flyout to the side. Nothing ever covers the screen.
• expand — hovering widens the rail back into the full menu, floating over the page, and it collapses again when the pointer leaves.

Submenus on a rail

A group cannot expand inside a 56px rail, so it opens a flyout to the side instead — on hover, with a short grace period so the diagonal trip into it does not close it. The flyout is titled with the name of the group it belongs to, points back at the icon it came from, and caps to of the screen and scrolls, so a group with twenty children stays reachable.

A group gets no tooltip — the flyout already names it, and stacking a tooltip over the children it just revealed is the one thing you do not want. Tooltips are for leaf items, whose label has nowhere else to go.

Step 5 — pick which toggle the operator sees

You now have two: the zone's edge tab, and the menu's own button. Keep whichever suits the design and turn the other off — the zone's Toggle button field set to None, or the menu's showToggle set to false. Both collapse the same zone, so either works.

The zone leads, the menu follows

Inside a collapsible zone you do not set collapsible, collapsed or collapsedWidth on the widget. The zone owns the width and the collapsed state; the menu reads them, draws itself at the rail width it was given, and its toggle collapses the zone so the layout reflows. That keeps one collapsed state instead of two that can disagree — which is what made the widget and the zone fight each other if you configured both.

Every zone field is per breakpoint, so set Collapsed width to 0 on mobile to have the sidebar get out of the way entirely there.

Collapsing a menu that is not in a zone

A Vertical Menu placed directly on a view can collapse on its own. Turn on collapsible, then set collapsedWidth (the rail, default 56) and expandedWidth (default 240). The expanded width belongs to the menu, not to the widget box, which is what lets a narrow rail open out to a full panel. collapsed sets the starting state and is bindable — bind it to a client variable to remember the operator's choice across screens.

A collapsible menu declares both of its widths, so a sibling in a flex or grid container reflows when it closes. A hover peek is the exception and always draws OVER the page: reflowing a whole screen for a glance makes the content jump out from under the cursor and back a moment later.

The hover panel matches its surroundings

The panel that floats out on hover has to be opaque, so it paints the background you set on the menu itself; failing that, the background of the view around it; and only failing both does it fall back to the theme surface. Set a background on the menu (or on its view) and the panel follows it instead of appearing as a pale slab over a dark screen.