Navigation menu

Who it’s for

Anyone building a dashboard that outgrew one screen. Once the overview, the device list, the alarms and the reports each live in their own dashboard state, people need a way to move between them that is visible from anywhere on the page — not a link buried in a card, and not the breadcrumb, which only walks back the way they came. This is the row of tabs across the top, or the column down the side, that says where they can go and where they are.

What it does

A dashboard with states named default, devices, alarms, reports and users gets one menu with five buttons, each naming its state. Someone on the overview sees the Overview button underlined; clicking Alarms replaces the current state with the alarm page and moves the underline with it. Nothing else on the dashboard has to know the menu exists.

• Every button carries an icon, a label and the state it opens, so the menu reads as a navigation bar rather than a row of unlabeled controls.
• The same menu stands up as a sidebar: set Orientation to Vertical and the buttons fill the width of the widget in a column, with the active one marked by a bar down its leading edge instead of a line underneath.
• The button matching the state you are on is highlighted, and it keeps up when the state is changed by something else — a card, a table row, the browser back button.
• One choice decides what every click does: add a state to the breadcrumb, replace the state you are on, or stay where you are and rewrite a single state parameter.
• Rewriting a parameter turns the menu into an entity switcher. Set Parameter name to entityId and give each button the id of a site, and one set of dashboard pages answers for every site, with the tabs showing which one is in view.
• The buttons scroll with arrows when there are more of them than the widget has room for — sideways in a horizontal menu, up and down in a vertical one — so a long menu does not wrap or clip.
• The menu carries no data of its own and reads no telemetry. It moves around the dashboard it sits on, and does not open other dashboards or external addresses.

How to set up

Data keys

The navigation menu takes no data at all — no datasource, no keys, no time window. It is configured entirely from its own settings, so it can be dropped onto any dashboard, including one whose entity aliases are not set up yet.

Menu

• Buttons — five buttons by default, named Overview, Devices, Alarms, Reports and Users. One row per button, drawn left to right, each with four fields: Icon (optional, leave it empty for a text-only button), Label, State (the dashboard state id the button opens, such as alarms), and Parameter value (what this button writes into the parameter named below). A row with neither a label nor an icon is skipped.
• Show icons — on by default. Off leaves every button as a plain label and hides the icon field, which is also how an icon comes off: the icon picker cannot be cleared once it holds one.
• On click — Update the current state by default, which is what a row of tabs usually wants: the state you are on is replaced, and the breadcrumb stays one entry long. Open a new state adds an entry each time, so the breadcrumb records the path. Change the parameter only keeps the current state and rewrites one of its parameters.
• Parameter name — empty by default. The one state parameter the buttons write, such as entityName or view. Each button sets its own value for it in Parameter value. Left empty, no parameter is touched and the buttons only change state. Every other parameter of the state being left is carried over, so the entity a dashboard is scoped to survives the jump.

How to customize

• To stand the menu up as a sidebar — Orientation is Horizontal by default; set it to Vertical and every button spans the width of the widget with its label on the left, with the scroll arrows at the top and bottom.
• To mark the active button with a filled shape instead of a line — Button style is Mark the active button with a line by default; set it to Fill the active button, or to Color the active label only for a menu with no mark beyond the color.
• To match the accent color of your dashboard — edit Active color, which paints the underline, the fill and the active label together.
• To tone the inactive buttons up or down — edit Label color, which also colors the scroll arrows.
• To make the labels bigger, smaller or lighter — edit Label font.
• To center the menu, push it to the far end, or spread the buttons evenly across the widget — Alignment is Start by default; set it to Center, End or Stretch. It follows the orientation: left to right in a horizontal menu, top to bottom in a vertical one.
• To remove the hairline the active mark sits on — turn off Menu line. It runs the length of the buttons rather than of the widget, and moves to the trailing side when the menu is vertical.
• To keep the line visible on a dark dashboard — edit Line color, which is a light gray by default and disappears against a dark background.
• To choose which button is highlighted before anyone clicks — set Active by default to its position in the list. It applies only while neither the state nor the parameter matches any button; 0 highlights nothing.

Tips

• Give the menu its own thin row across the top of the dashboard, or a narrow column down the left, and let every state include it. The widget ships transparent, with no border or corner rounding, so it sits on the dashboard background rather than in a card.
• Keep On click on Update the current state for a top-level menu. Open a new state is for a menu that leads deeper into a drill-down, where the breadcrumb back to the previous page is worth having.
• When the menu switches entities through Parameter name, the state parameter entityId arrives as an object rather than as plain text; the widget matches it on the id inside, so a Parameter value holding the entity id is what the buttons need.
• The buttons are inert while the dashboard is in edit mode, so arranging the layout never navigates away from the state you are working on.