> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: About Dashboard Page Navigation

## Article: About Dashboard Page Navigation

## Article Link: https://dev.wix.com/docs/sdk/host-modules/dashboard/about-dashboard-page-navigation.md

## Article Content:

# About Dashboard Page Navigation

You can call the Dashboard API's [`navigate()`](https://dev.wix.com/docs/sdk/host-modules/dashboard/navigate.md) method to navigate Wix users to pages in the dashboard. These can be pages made by Wix, pages added by you, or pages added by 3rd-party apps.

When calling `navigate()`, you must provide the page ID for the dashboard page to navigate to. For instructions on how to find the page IDs of your dashboard pages, and for a full list of Wix page IDs, see [Page IDs](https://dev.wix.com/docs/sdk/host-modules/dashboard/page-ids.md).

## Using `relativeUrl` for internal navigation

When calling `navigate()`, you can pass a `relativeURL`. This is a URL segment appended to the base URL of the selected page (`destination`) that allows you to navigate to a page with some internal state information.

A `relativeUrl` can include the following:

+ **Pathname**: Parts of a URL path to append to the base `destination` URL passed to `navigate()`. For example, `/some/internal/path`.
+ **Search**: A string containing search (query) params used to set the internal state of the page. For example, `?param1=value1&param2=value2`.
+ **Hash (fragment identifier)**. Typically used to identify some content on the page. For example, `#subheading1`.

To call `navigate()` with the a `relativeURL` made from the above examples, you would use the following code:

```js
dashboard.navigate({pageId: <your-page-id>, relativeUrl: "/some/internal/path?param1=value1&param2=value2#subheading1"})
```

### Consuming URL segments

You can consume an appended URL segment in your code using [`observeState()`](https://dev.wix.com/docs/sdk/host-modules/dashboard/observe-state.md). `observeState()` returns the contextual state of the page in a `componentParams` object, and environmental information of the dashboard in an `environmentState` object. The path appended to the page URL by `relativeURL` is stored in the `componentParams` object's [`location`](https://dev.wix.com/docs/sdk/host-modules/dashboard/observe-state.md#about-pathname).

`location` contains properties corresponding with those passed in `relativeUrl` (`pathname`, `search`, `hash`), as well as the `pageId`.

The example below shows how to access the `location` object:

```javascript
dashboard.observeState((componentParams, environmentState) => {
  // This value is logged on initialization and whenever either `componentParams` or `environmentState` changes. 
  console.log(componentParams.location);
});
```

## Managing navigation history

`navigate()` accepts an optional `history` parameter with a value of either `"push"` (default) or `"replace"`. This parameter determines whether the URL of the page being navigated to is added to the browser's [session history](https://developer.mozilla.org/en-US/docs/Web/API/History_API), or replaces the URL in the current entry.

For example, your dashboard page may contain a table, and you may want any filtering and sorting done on the table to sync with the URL in the address bar so that the user can easily copy and share it. To achieve this you would navigate to the same page with an updated `relativeURL`. However, every time you navigate this way, the new URL is added to the browser's session history. To prevent this, you can pass `{history: "replace"}` when calling `navigate()`. Now instead of adding a new entry, the browser updates the current entry, and the user still only requires 1 "back" or "forward" click to navigate through the page.

## Overlay pages

`navigate()` offers 2 options for displaying the page you're navigating to:

- **Main display mode**: The browser replaces the current main page content with the new page.
- **Overlay display mode**: The new page is displayed in a modal overlaid on top of the main page.

Overlay pages allow you to navigate to a related page, like a settings page, without losing the original context. The original page remains in the background, and when the overlay page is closed the user returns to the original page.

> **Note**: The overlay page modal is not related to the [dashboard modal extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/dashboard-extensions/dashboard-modals/about-dashboard-modals.md). Overlay pages are used for navigation, while dashboard modal extensions are intended to get user input in response to an action taken on a dashboard page.

### Display mode

`navigate()` accepts an optional `displayMode` parameter with a value of `"main"`, `"overlay"`, or `"auto"` (default).

`"main"` and `"overlay"` select their corresponding display mode. `"auto"` (default) causes the page to be loaded in the current context. This means if `navigate()` is called from the main page, the main page changes. If it's called from an overlay page, the overlay content changes to the new page.

When Wix renders a dashboard page, that page is passed a parameter recording whether it was opened as a main or overlay page. This information allows you to adjust the page's UX or logic accordingly, however in most cases this isn't necessary as Wix handles the adjustments automatically. 
You can check this using [`observeState()`](https://dev.wix.com/docs/sdk/host-modules/dashboard/observe-state.md) to retrieve the `componentParams` object's `displayMode` property.

### Navigating from within an overlay page

If you call `navigate()` inside an overlay page using `"overlay"` or `"auto"`, the new page loads within the same modal.

If you call `navigate()` inside an overlay page using `"main"`, the overlay page closes and the main page is updated.

If a user navigates back from the first overlay page that was opened in the modal, the modal closes and they return to the original context. If the user then navigates forward, the modal with the overlay page is reopened.

All overlay pages contain an **X** which closes the modal, and a **left arrow** with the same behavior as the browser's back button. The `navigateBack()` method provides a way to implement the back button behavior in code.

### Page URLs in overlay pages

The URL in the browser's address bar doesn't change to reflect the URL of the current overlay page. For example, if you navigate from a calendar page to its settings page in the main browser window, the end of the path in the address bar changes from `/calendar` to `/calendar/settings`. But if you navigate to the settings page in an overlay page, the path in the address bar remains `/calendar`.

This has no effect on browser navigation, only what appears in the browser's address bar, so users can navigate back and forward between pages as normal within and outside the overlay page modal. (The URLs of pages opened in overlay mode are added to the browser's session history as normal.)

## See also
+ [Dashboard API](https://dev.wix.com/docs/sdk/host-modules/dashboard/introduction.md)
+ [`navigate()`](https://dev.wix.com/docs/sdk/host-modules/dashboard/navigate.md)