# Navigation controls Widget type: `opendash-widget-od-navigation` · Plugin: `@opendash/plugin-monitoring` ![Navigation controls preview](../../../../../_attachments/opendash/widgets/assets/widget-previews/od-navigation.png) ## Description Adds navigation elements to quickly navigate between internal components, dashboards and external links. Each element is rendered as a button; clicking it either opens another dashboard, follows an internal route, opens an external page in a new tab, or fires an HTTP request (POST/PUT/GET/DELETE) to an external endpoint. Buttons can be laid out horizontally (default) or vertically, and each carries its own label, icon and color. ## Data requirements This widget does not use any data items (`dataItems` is `null`) and performs no data fetching (`dataFetching` is `null`). It is purely a navigation/control widget. At least one navigation element must be configured, otherwise the widget shows the error "No controls defined". ## Options | Option | Type | Default | Description | | --- | --- | --- | --- | | `elements` | `Element[]` | `[]` | The list of navigation buttons. Each element has the fields below. | | `vertical` (Vertical Alignment) | `boolean` | `false` | If enabled, buttons are stacked vertically; otherwise they are arranged horizontally and share the available width. | Each entry in `elements` is one of three element types and has these fields: | Field | Type | Default | Description | | --- | --- | --- | --- | | `label` (Label) | `string` | `""` | Text shown on the button. | | `icon` (Icon) | `string` | `""` | Icon shown on the button (chosen with the icon picker). | | `color` (Color) | `string` | `var(--opendash-primary-color)` for dashboard elements | Button background color. | | `type` (Type) | `"dashboard" \| "link" \| "external"` | `"dashboard"` (Dashboard button) | The kind of navigation target. | Type-specific fields: | Field | Applies to | Type | Default | Description | | --- | --- | --- | --- | --- | | `dashboard` (Target) | Dashboard | dashboard reference | `null` | The dashboard to open. Only dashboards belonging to a known source are selectable. | | `link` (Target) | Internal Link | `string` | `""` | An internal application route to navigate to. | | `external` (Target) | External Link | `string` | `""` | The external URL or endpoint. | | `method` (Method for request) | External Link | `"SHOW" \| "POST" \| "PUT" \| "GET" \| "DELETE"` | `"SHOW"` | `SHOW` opens the page in a new tab ("Open Page in new Tab"); the HTTP verbs send a request to the URL and show a success/error notification with the response text. | | `headers` (Header Information) | External Link | `{ key: string; value: string }[]` | `[]` | Request headers (Key / Value pairs). Only shown when the method is not `SHOW`. | | `body` (Body) | External Link | `string` | `""` | Request body. Only used for `POST` and `PUT` requests. | ## Presets - **Navigation controls** — Adds navigation elements to quickly navigate between internal components, dashboards and external links. Tagged `control`. Default config: empty `elements` list and a borderless widget style (`_style.borderless: true`). ## How to use 1. Add the "Navigation controls" widget to a dashboard. 2. In the settings, add buttons using one of the three add buttons: **Dashboard** (internal dashboard), **Internal Link** (in-app route) or **External Link** (external URL or HTTP request). 3. For each button, set a **Label**, pick an **Icon** and a **Color**. 4. For a dashboard button, select the target dashboard. For an internal link, enter the route. For an external link, enter the URL and choose a **Method**: keep `Open Page in new Tab` to simply open the URL, or pick an HTTP verb to fire a request — then add **Header Information** (Key/Value) and, for POST/PUT, a request **Body**. 5. Optionally enable **Vertical Alignment** to stack the buttons vertically instead of side by side. 6. Save. At least one element must be defined or the widget displays "No controls defined".