> For the complete documentation index, see [llms.txt](https://docs.blynk.io/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blynk.io/en/html-widget-developer-guide/navigation.md).

# Navigation

Two kinds of navigation:

* **Native screens** — the bound device's info screen, its timeline, and the organization's automations. Available on **web and mobile**.
* **Dashboard pages** — pages configured as targets of this widget. **Mobile only.**

### Open the device info screen

> Opens the bound device's Device info screen.

```js
bridge.openDeviceInfo()  // → Promise<null>
```

**Parameters:** none — passing any argument rejects with `invalid_request`.

If the widget is already shown inside the bound device's info screen, it switches to the info tab instead of opening a new screen.

**Permission:** `VIEW_DEVICE_INFO`.

### Open the device timeline

> Opens the bound device's Timeline screen, optionally at one event.

```js
bridge.openDeviceEvents(options?)  // → Promise<null>
```

| Name                 | Type     | Required | Description                                                                                                  |
| -------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `options.logEventId` | `string` | no       | `DeviceEvent.id` from `getDeviceEvents()` under the current binding. The screen scrolls to and highlights it |

`options` must be a plain object with only `logEventId`. An unknown ID rejects with `event_not_found`.

**Permission:** `VIEW_EVENTS`.

### Open automations

> Opens the organization's Automations list (not filtered by device).

```js
bridge.openAutomations()  // → Promise<null>
```

**Parameters:** none — passing any argument rejects with `invalid_request`.

**Permission:** `VIEW_AUTOMATIONS`.

**Common rules for native screens**

* **A user gesture is required.** Call them directly from a click, tap or key-press handler — not after an `await`, and not from a timer, a load handler or a value callback. Otherwise they reject with `user_gesture_required`. Check permissions when you render the link: checking on click, before the call, spends the gesture.
* They resolve `null` once the host has accepted the hand-off, not when the new screen finishes loading. The widget usually goes to the background right after.
* **Web:** one hand-off at a time. A second call while the previous one is still being handed off (about a second) rejects with `navigation_in_progress`; a request with no answer rejects after 10 seconds with `request_timeout`.
* `isPageActionsSupported()` doesn't apply to them — feature-detect the method instead.

**Rejects with** `invalid_request`, `user_gesture_required`, `navigation_in_progress`, `event_not_found`, `request_timeout`, `server_error`, `device_unavailable`, `bridge_destroyed`.

**Example**

```js
if (typeof bridge.openDeviceInfo === 'function' &&
    await bridge.isPermissionAllowed('VIEW_DEVICE_INFO').catch(() => true)) {
  infoLink.hidden = false;
  infoLink.addEventListener('click', () => bridge.openDeviceInfo().catch(() => {}));
}

eventRow.addEventListener('click', () =>
  bridge.openDeviceEvents({ logEventId: event.id }).catch(() => {}));
```

***

### List dashboard pages (mobile only)

> Returns the page targets configured on this widget, in `showPage` order.

```js
bridge.getPages()  // → Promise<Array<{ id: number, name: string }>>
```

The dashboard-page methods **don't exist on web** — `bridge.getPages` and `bridge.showPage` are `undefined` there, so an unguarded call throws a `TypeError`. Always gate on the capability flag *and* the method:

```js
const canNavigate = bridge.isPageActionsSupported() && typeof bridge.showPage === 'function';
```

**Resolves with** only the page targets configured on this HTML Widget:

* The array position **is** the `showPage` argument: `getPages()[0]` is opened by `showPage(0)`.
* Pages of the template that aren't configured as targets of this widget never appear.
* Duplicates are kept: a page configured twice appears twice, at both positions.
* A target whose page can't be resolved keeps its slot with `name: ''`.
* No targets configured, or no template available, gives `[]`.
* The list refreshes when the widget binding updates — rebuild navigation from a fresh read rather than caching it across reloads.
* It isn't filtered by role or plan, so a listed target doesn't guarantee that navigation succeeds.

A page `id` is for display and bookkeeping — **never** pass it to `showPage()`. If you sort or filter the list for display, keep each entry's original position.

### Open, close and leave dashboard pages (mobile only)

> Opens a configured page target, closes the current page, or returns to the main dashboard.

```js
bridge.showPage(index)   // opens the configured target at that 0-based position
bridge.closePage()       // closes the widget's containing page (one step back)
bridge.closeAllPages()   // returns to the main dashboard
```

| Name    | Type     | Required | Description                                |
| ------- | -------- | -------- | ------------------------------------------ |
| `index` | `number` | yes      | Position in `getPages()` — not a page `id` |

* There is no "page opened" callback. Give buttons a pressed state on `pointerdown`; don't show a spinner that never resolves.
* A bad index — not an integer (`invalid_request`), or outside the configured targets (`index_out_of_bounds`, `details: { index, count }`) — is reported through `onError` and fails the call. Depending on the app, the failure is thrown synchronously or returned as a rejected Promise, so wrap the call to handle both.
* There is no page permission for `isPermissionAllowed`, and `isPageActionsSupported()` is not authorization.

**Example**

```js
function navigate(call) {
  try { Promise.resolve(call()).catch(() => {}); } catch (e) { /* already reported through onError */ }
}

if (canNavigate) {
  const pages = await bridge.getPages();
  pages.forEach((page, index) => {
    const button = document.createElement('button');
    button.textContent = page.name || `Page ${index + 1}`;
    button.addEventListener('click', () => navigate(() => bridge.showPage(index)));   // index, not page.id
    nav.appendChild(button);
  });
  backButton.addEventListener('click', () => navigate(() => bridge.closePage()));
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.blynk.io/en/html-widget-developer-guide/navigation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
