Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Frontend Modules

Wix Design System (WDS)

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

import { Property, PropertyList, ExpandableSection, RequestResponseExamples } from "@wix/docs-ui/content";

{/* Generated by @wix/tw-typedoc-to-wix-docs from packages/site-service-router/src/definition/index.ts. Do not edit this file directly — edit the TSDoc in the source package. */}

# Router Functions

## navigateTo()

Navigates to a page on the site, or opens a link that isn't a page on the site.

Call it in response to something the site visitor does, such as clicking a button. While the page
renders on the server, it does nothing.

With `type: 'ExternalLink'`, the method calls `window.open(href, target)` and resolves `true`. In the editor,
it does nothing and resolves `false` unless `target` is `'_blank'`.

Otherwise, the method navigates to `href` in the current tab. When `href` is the page the site visitor is
already on, the method stays on the page, updates the query parameters in the page's URL, and resolves
`false`.

The promise rejects when the navigation fails, such as when the new page can't load.

### Method Declaration

```ts
navigateTo(link: RouterLink, options?: NavigateOptions): Promise<boolean>
```

### Method Parameters

<PropertyList bordered>
  <Property name="link" type="RouterLink" required>
    Link to navigate to.
    <ExpandableSection name="Child Properties">
      <PropertyList>
        <Property name="href" type="string" required>
          Where to navigate. For a page on the site, specify the site root URL followed by the page's path, such as
          `https://www.example.com/shop`. Get the site root URL from `siteUrl` in `@wix/site-service-url`. This form
          works on the published site and in the editor's preview. It can include query parameters, as in
          `.../shop?sort=price`. For an item on a router page, specify the item's full path, such as
          `.../News/spring-sale`, and the router decides which page shows it.

          For a URL that isn't a page on the site, such as `https://www.wix.com`, also specify `type:
          'ExternalLink'`.
        </Property>
        <Property name="target" type="'_self' | '_blank'">
          Tab that `window.open()` uses when `type` is `'ExternalLink'`: `'_blank'` for a new tab, `'_self'` for the
          current tab. When it isn't set, `window.open()` uses a new tab.

          Without `type`, the method ignores `target` and navigates in the current tab.
          <ExpandableSection name="Enum Values">
            <PropertyList>
              <Property name="'_self'" />
              <Property name="'_blank'" />
            </PropertyList>
          </ExpandableSection>
        </Property>
        <Property name="type" type="'ExternalLink'">
          `'ExternalLink'` opens `href` with `window.open(href, target)` instead of navigating to it, also when
          `href` is a page on the site.

          In the editor, `'ExternalLink'` does nothing and resolves `false` unless `target` is `'_blank'`.
        </Property>
      </PropertyList>
    </ExpandableSection>
  </Property>
  <Property name="options" type="NavigateOptions">
    Options for the navigation.
    <ExpandableSection name="Child Properties">
      <PropertyList>
        <Property name="disableScrollToTop" type="boolean">
          Whether to keep the current scroll position instead of scrolling to the top of the page, when `href` is the
          page the site visitor is already on. When `href` is another page, it has no effect.

          Default: `false`
        </Property>
      </PropertyList>
    </ExpandableSection>
  </Property>
</PropertyList>

### Returns

<PropertyList bordered>
  <Property name="Return Type:" type="Promise<boolean>">
    Promise that resolves with `true` when the method went to a different page on the site, or called
    `window.open()`.

    `false` when the site visitor stays on the current page. That happens when `href` is the current page,
    when the site can't route to `href`, and while the page renders on the server. In the platform worker,
    while the page renders on the server, it resolves `undefined`.
  </Property>
</PropertyList>

### Examples

<RequestResponseExamples defaultName="navigateTo" requestName="JavaScript" requestType="JavaScript" examples={[
  {
    title: `Go to the shop from a button`,
    content: {
      methodExample: {
        Request: `~~~tsx
import { useState } from 'react'
import { useService } from '@wix/services-manager-react'
import { RouterDefinition } from '@wix/site-service-router/definition'
import { UrlDefinition } from '@wix/site-service-url/definition'

function BrowseShopButton() {
    const routerService = useService(RouterDefinition)
    const urlService = useService(UrlDefinition)
    const [failed, setFailed] = useState(false)

    const goToShop = async () => {
        const navigated = await routerService
            .navigateTo({ href: \`\${urlService.siteUrl}/shop\` })
            .catch(() => false)
        setFailed(!navigated)
    }

    return (
        <>
            <button onClick={goToShop}>Browse the shop</button>
            {failed && <p>The shop isn't available right now.</p>}
        </>
    )
}
~~~`
      }
    }
  },
  {
    title: `Sort the current page's items without scrolling to the top`,
    content: {
      methodExample: {
        Request: `~~~ts
// routerService and urlService are resolved as in the first example, on the site's /shop page.
async function sortByPrice() {
    return routerService.navigateTo({ href: \`\${urlService.siteUrl}/shop?sort=price\` }, { disableScrollToTop: true })
}
~~~`
      }
    }
  },
  {
    title: `Open an external link in a new tab`,
    content: {
      methodExample: {
        Request: `~~~ts
// routerService is resolved as in the first example.
routerService.navigateTo({ href: 'https://www.wix.com', type: 'ExternalLink', target: '_blank' })
~~~`
      }
    }
  }
]} />