Skip to main content
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. 
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: 
// 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)
Use waitForSelector() after goto() to ensure specific content has loaded before proceeding.

​
page.url()

Gets the current page URL. 
page.url(): Promise<string>
Returns: Promise<string> - Current URL Example: 
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). 
page.progress(): Promise<number>
Returns: Promise<number> - Load progress percentage Example: 
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. 
page.show(animate?: boolean): Promise<void>
Parameters:
  • animate (optional): Whether to animate the transition (default: true)
Returns: Promise<void> Example: 
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. 
page.hide(animate?: boolean): Promise<void>
Parameters:
  • animate (optional): Whether to animate the transition (default: true)
Returns: Promise<void> Example: 
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()
Use show() and hide() to manage multiple pages in a browser, similar to switching tabs.

​
page.setUserAgent()

Sets a custom User-Agent string for the page. 
page.setUserAgent(userAgent: string): Promise<void>
Parameters:
  • userAgent: User-Agent string to set
Returns: Promise<void> Example: 
// 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: 
// 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)
Set the user agent before navigating to ensure it’s applied to all requests on the page.

​
Complete examples

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

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

// 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

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

// 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

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)
  }
}

Waiting

Wait for content after navigation

Events

Monitor navigation events

Page overview

Back to Page API overview