navigate()
Navigates the user to another page in the dashboard.
To identify a page to navigate to you can:
- Look up its page ID.
- Use a builder method to generate the destination object for a particular page. Several SDK modules include builder methods for the pages relevant to each module. For example,
bookings,blog, andecomall provide builder methods.
If you specify an invalid page ID when you call this function, navigate() throws Unknown link. With a scope, an unknown page instead falls back to the target scope's default page.
Note: Currently, you can't call navigate() to navigate to pages built when extending sites or building apps with Blocks.
You can specify how to display the page you're navigating to using the displayMode option.
There are two display modes available:
- 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 overlay on top of the main page.
You can also navigate the Wix user to a different scope, from a site to their account, from their account to a site, or directly between 2 sites, by specifying a scope in the destination. A cross-scope navigation is a full page load, optionally deep-linking to a page in the target scope. For what a scope is and how a scope switch behaves, see About Cross-Scope Navigation. See Cross-scope navigation below for this method's parameters.
Learn more about dashboard page navigation.
Method declaration
Parameters
| Name | Type | Description |
|---|---|---|
destination | Destination | Destination page to navigate to. |
options | NavigationOptions | Optional. Options for the navigation. |
Destination object
| Name | Type | Description |
|---|---|---|
pageId | string | ID of the page to navigate to. See Page IDs to find the appropriate ID. Required if you don't specify a scope. In a cross-scope navigation, omit it to land on the target scope's default page. |
relativeUrl | string | Optional. URL segment to append to the base URL of the selected page. Can include path segments, a query string, and a fragment identifier. Requires a pageId. Specifying a relativeUrl without a pageId throws. |
scope | ScopeTarget | Optional. Scope to navigate to, either the Wix user's account or a specific site. Omit it to navigate in the current scope. See Cross-scope navigation for more information. |
ScopeTarget object
| Name | Type | Description |
|---|---|---|
type | "site" | "account" | The kind of scope to navigate to. |
metaSiteId | string | Site ID of the site to navigate to, in GUID format. Required if type is "site". |
NavigationOptions object
| Name | Type | Description |
|---|---|---|
displayMode | "main" | "overlay" | "auto" | When using main, the browser replaces the current main page content with the new page. When using overlay, the new page is displayed in a modal overlaid on top of the main page."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.With a scope, the display mode takes effect once the target scope loads."overlay" is available only when you also specify a pageId. |
history | "push" | "replace" | Optional. Determines whether the URL of the page being navigated to is added to the browser's session history, or replaces the URL in the current entry. With a scope, this applies to the page the Wix user is leaving, so "replace" keeps the source page out of the Wix user's history. |
scopeQueryParams | Record<string, string> | Optional. Query params to add to the target scope's URL, for passing context across a scope switch. These values appear in the URL, browser history, and referrer headers, so never use them to pass secrets. For page-level query params, use relativeUrl instead.Limited to keys that don't begin with ws. The dashboard reserves those for its own deep-linking and drops them.Used only when you specify a scope. Specifying it without a scope throws. |
Cross-scope navigation
Specifying a scope navigates the Wix user out of the current scope and into another scope, from a site to their account, from their account into a site, or directly between 2 sites. The switch is one-way, and your code can't observe whether it happened. For what a scope is and how a scope switch behaves, including what happens to unsaved changes, see About Cross-Scope Navigation.
Important:
Moving into a site scope requires that the Wix user has access to that site. If they don't, the navigation fails once it reaches that site rather than navigate() throwing on the calling page. See Access requirements.
If the target scope is the one the Wix user is already in, there's no switch to make, and navigate() falls back to same-scope behavior:
- With a
pageId, it performs an ordinary in-scope navigation to that page. - Without a
pageId, it does nothing. The exception isdisplayMode: "overlay", which requires apageIdand throws without one even when the scope doesn't change. - The dashboard drops
scopeQueryParams, since it isn't tearing anything down to carry them across.
Deep-linking into the target scope is optional. Specify a pageId to land on a page, and a relativeUrl alongside it to restore that page's internal state. If the page doesn't exist or isn't installed in the target scope, the Wix user lands on that scope's default page instead.
The following calls throw synchronously, since each is a caller error rather than a runtime condition:
| Call | Error |
|---|---|
navigate({}), with neither a pageId nor a scope | navigate requires a pageId or a scope |
A relativeUrl with no pageId | relativeUrl requires a pageId |
scopeQueryParams with no scope | scopeQueryParams requires a scope (use relativeUrl for page query params) |
displayMode: "overlay" with a scope but no pageId | displayMode 'overlay' with a scope switch requires a pageId |
A "site" target whose metaSiteId isn't a valid GUID | scope.metaSiteId must be a GUID |
Examples
Note: To call this method in self-managed apps, you need to create a client. See the setup guide for more details.
Navigate to the dashboard's homepage
Navigate to your own app's page with some internal state
Open bookings settings page in an overlay page
Navigate to the home page as a main page from inside an overlay page
Navigate from a site to the Wix user's account
Navigate into a specific site and deep-link to one of its pages
Carry context across a scope switch
Specify scopeQueryParams to hand the target scope some context. In this example, the source page replaces its own history entry, so clicking Back doesn't return the Wix user to the site they just left:
Last updated: 17 September 2026