> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uplink.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Navigation

> Methods for navigating pages and checking URLs

Navigate to URLs and monitor page loading with the Page navigation API.

## Methods

### `page.goto()`

Navigates to a URL. Returns `true` if navigation succeeded, `false` otherwise.

```typescript theme={null}
page.goto(url: string, headers?: Record<string, string>, timeout?: number): Promise<boolean>
```

**Parameters:**

* `url`: URL to navigate to
* `headers` (optional): Custom HTTP headers to send with the request
* `timeout` (optional): Navigation timeout in milliseconds (default: varies)

**Returns:** `Promise<boolean>` - `true` if navigation succeeded

**Examples:**

```typescript theme={null}
// Basic navigation
await page.goto('https://example.com')

// With custom headers
await page.goto('https://api.example.com', {
  'Authorization': 'Bearer token123',
  'X-Custom-Header': 'value'
})

// With timeout (60 seconds)
await page.goto('https://slow-site.com', {}, 60000)
```

<Tip>
  Use `waitForSelector()` after `goto()` to ensure specific content has loaded before proceeding.
</Tip>

### `page.url()`

Gets the current page URL.

```typescript theme={null}
page.url(): Promise<string>
```

**Returns:** `Promise<string>` - Current URL

**Example:**

```typescript theme={null}
await page.goto('https://example.com/page1')
const url = await page.url()
console.log('Current URL:', url)  // https://example.com/page1

// Check if navigation succeeded
await page.click('#link')
await new Promise(resolve => setTimeout(resolve, 1000))
const newUrl = await page.url()
console.log('Navigated to:', newUrl)
```

### `page.progress()`

Gets page load progress as a percentage (0-100).

```typescript theme={null}
page.progress(): Promise<number>
```

**Returns:** `Promise<number>` - Load progress percentage

**Example:**

```typescript theme={null}
page.goto('https://example.com')

// Poll progress while loading
const interval = setInterval(async () => {
  const progress = await page.progress()
  console.log(`Loading: ${progress}%`)

  if (progress === 100) {
    clearInterval(interval)
    console.log('Page fully loaded')
  }
}, 500)
```

### `page.show()`

Brings the page to the foreground, making it visible to the user.

```typescript theme={null}
page.show(animate?: boolean): Promise<void>
```

**Parameters:**

* `animate` (optional): Whether to animate the transition (default: `true`)

**Returns:** `Promise<void>`

**Example:**

```typescript theme={null}
const page1 = await browser.newPage()
const page2 = await browser.newPage()

await page1.goto('https://example.com')
await page2.goto('https://google.com')

// Switch to page1 (with animation)
await page1.show()

// Wait a bit
await new Promise(resolve => setTimeout(resolve, 2000))

// Switch to page2 (no animation)
await page2.show(false)
```

### `page.hide()`

Hides the page, removing it from view.

```typescript theme={null}
page.hide(animate?: boolean): Promise<void>
```

**Parameters:**

* `animate` (optional): Whether to animate the transition (default: `true`)

**Returns:** `Promise<void>`

**Example:**

```typescript theme={null}
const page = await browser.newPage()
await page.goto('https://example.com')

// Hide the page
await page.hide()

// Do work in background
await page.evaluate(() => {
  // Page is hidden but still active
  console.log('Running in background')
})

// Show again when done
await page.show()
```

<Tip>
  Use `show()` and `hide()` to manage multiple pages in a browser, similar to switching tabs.
</Tip>

### `page.setUserAgent()`

Sets a custom User-Agent string for the page.

```typescript theme={null}
page.setUserAgent(userAgent: string): Promise<void>
```

**Parameters:**

* `userAgent`: User-Agent string to set

**Returns:** `Promise<void>`

**Example:**

```typescript theme={null}
// Set desktop Chrome user agent
await page.setUserAgent(
  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36'
)

await page.goto('https://example.com')

// Verify user agent
const ua = await page.evaluate(() => navigator.userAgent)
console.log('User agent:', ua)
```

**Common user agents:**

```typescript theme={null}
// Desktop Chrome (Windows)
const desktopChrome = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36'

// Desktop Safari (Mac)
const desktopSafari = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_3_1) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Safari/605.1.15'

// Mobile Chrome (Android)
const mobileChrome = 'Mozilla/5.0 (Linux; Android 14) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.6261.64 Mobile Safari/537.36'

// iPhone Safari
const iPhoneSafari = 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_3_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Mobile/15E148 Safari/604.1'

await page.setUserAgent(desktopChrome)
```

<Warning>
  Set the user agent before navigating to ensure it's applied to all requests on the page.
</Warning>

## Complete examples

### Navigation with verification

```typescript theme={null}
const targetUrl = 'https://example.com/dashboard'
const success = await page.goto(targetUrl)

if (!success) {
  throw new Error('Navigation failed')
}

// Verify we're on the right page
const currentUrl = await page.url()
if (!currentUrl.includes('/dashboard')) {
  throw new Error('Wrong page loaded')
}

console.log('Successfully navigated to dashboard')
```

### Handling redirects

```typescript theme={null}
const initialUrl = 'https://example.com/redirect-me'
await page.goto(initialUrl)

// Wait a bit for redirect
await new Promise(resolve => setTimeout(resolve, 2000))

const finalUrl = await page.url()
console.log('Redirected from:', initialUrl)
console.log('Redirected to:', finalUrl)
```

### Authenticated navigation

```typescript theme={null}
// Navigate with auth header
const success = await page.goto('https://api.example.com/data', {
  'Authorization': 'Bearer ' + accessToken,
  'Accept': 'application/json'
})

if (!success) {
  console.error('Failed to access protected resource')
  return
}

// Extract data
const data = await page.evaluate(() => {
  const pre = document.querySelector('pre')
  return pre ? JSON.parse(pre.textContent) : null
})

console.log('API response:', data)
```

### Progress monitoring

```typescript theme={null}
async function navigateWithProgress(url) {
  console.log('Starting navigation to:', url)

  // Start navigation
  const navigationPromise = page.goto(url)

  // Monitor progress
  let lastProgress = 0
  const progressInterval = setInterval(async () => {
    const progress = await page.progress()

    if (progress !== lastProgress) {
      console.log(`Progress: ${progress}%`)
      lastProgress = progress
    }

    if (progress === 100) {
      clearInterval(progressInterval)
    }
  }, 200)

  // Wait for navigation to complete
  await navigationPromise

  console.log('Navigation complete')
}

await navigateWithProgress('https://example.com')
```

### Single-page application navigation

```typescript theme={null}
// For SPAs that use client-side routing
await page.goto('https://spa-example.com')

// Click a navigation link
await page.click('#nav-link')

// Wait for URL to change
const initialUrl = await page.url()
let newUrl = initialUrl

while (newUrl === initialUrl) {
  await new Promise(resolve => setTimeout(resolve, 100))
  newUrl = await page.url()
}

console.log('Navigated to:', newUrl)

// Or wait for content to change
await page.waitForSelector('.new-page-content')
```

## Error handling

```typescript theme={null}
try {
  const success = await page.goto('https://example.com', {}, 30000)

  if (!success) {
    console.error('Navigation returned false')
  }
} catch (error) {
  if (error.message.includes('timeout')) {
    console.error('Navigation timed out after 30 seconds')
  } else {
    console.error('Navigation error:', error)
  }
}
```

## Related

<CardGroup cols={2}>
  <Card title="Waiting" icon="hourglass" href="/api-reference/page/waiting">
    Wait for content after navigation
  </Card>

  <Card title="Events" icon="bell" href="/api-reference/page/events">
    Monitor navigation events
  </Card>

  <Card title="Page overview" icon="window-maximize" href="/api-reference/page/overview">
    Back to Page API overview
  </Card>
</CardGroup>