Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Puppeteer’s Page API represents a browser tab and provides the methods you need to navigate, interact with page elements, run JavaScript in the page, wait for events, take screenshots, and generate PDFs. For a full-page image, use page.screenshot({ fullPage: true }); for a PDF, use page.pdf(), noting that it uses print styles by default.

What the Puppeteer Page API does

A Page is Puppeteer’s per-tab API surface. It gives your script access to navigation, frames, element interaction, page-context JavaScript, waits, screenshots, and PDF output. The current official Page reference is for Puppeteer 25.12.0; check the documentation for the version installed in your project if an option’s behavior matters to your workflow: Puppeteer Page API reference.

Launch a browser, navigate, and capture a page

This complete Node.js example launches Chromium, opens a page, navigates to a URL, saves a full-page PNG, and closes the browser even if capture fails. Install Puppeteer in your project with npm install puppeteer, then save this as capture.js and run node capture.js.

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  try {
    const page = await browser.newPage();
    const response = await page.goto('https://example.com', {
      waitUntil: 'networkidle2',
      timeout: 30000,
    });

    if (response && !response.ok()) {
      throw new Error(`Navigation returned HTTP ${response.status()}`);
    }

    await page.screenshot({ path: 'page.png', fullPage: true });
  } finally {
    await browser.close();
  }
})();

page.goto() resolves to the response for the main resource. It can return null for about:blank or same-URL navigation that only changes the hash. Valid HTTP error responses such as 404 or 500 do not necessarily cause goto() to throw; inspect response.status() when your automation must treat them as failures. The Page reference also documents that headless shell has a status-handling caveat, so verify behavior against the browser mode and Puppeteer version you run: Page reference and Page.goto reference.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
#1 Best Overall
Sale
HTML and CSS: Design and Build Websites
  • HTML CSS Design and Build Web Sites
  • Comes with secure packaging
  • It can be a gift option

Choose and interact with page elements

For user-like actions such as clicking or filling a control, Puppeteer recommends Locators. A Locator waits for the target to exist and be in a suitable state for the action, reducing races caused by clicking before a page has rendered the control. See the Page interactions guide.

const locator = page.locator('button[type="submit"]');
await locator.click();

If an action triggers navigation, start the navigation wait and action together. Otherwise the click can begin navigating before the wait is registered:

const [response] = await Promise.all([
  page.waitForNavigation(),
  page.click('a.some-link'),
]);

if (response && !response.ok()) {
  throw new Error(`Navigation returned HTTP ${response.status()}`);
}

For a one-off lookup, page.$eval(selector, callback) passes the first matching element to the callback and throws if it finds no match. For interactions that need readiness checks, use a Locator instead of assuming the element is ready just because a selector exists.

Run JavaScript in the page

page.evaluate() runs a function in the page’s JavaScript context and returns its result to Node.js. If the function returns a Promise, Puppeteer waits for it to resolve. Use it for page-side inspection or computation, not as a substitute for user-like interactions that should use Locators.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #2
Sale
Web Design with HTML, CSS, JavaScript and jQuery Set
  • Brand: Wiley
  • Set of 2 Volumes
  • A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
const title = await page.evaluate(() => document.title);
console.log(title);

Use page.evaluateHandle() when you need to retain a reference to a page-side object rather than transfer a serializable result. It returns a handle; dispose of handles when they are no longer needed. The behavior and return types are described in the evaluate reference and Page reference.

Take viewport, full-page, or clipped screenshots

page.screenshot() returns image bytes by default; configure it to return base64 if that is more useful to your application. Pass path to write to disk. Puppeteer infers the image type from the filename extension when you do not specify a type. A standard screenshot captures the viewport; set fullPage: true to capture the full page, or pass a clip rectangle to capture a specific region.

// Viewport capture
await page.screenshot({ path: 'viewport.png' });

// Full-page capture
await page.screenshot({ path: 'full-page.png', fullPage: true });

// Capture a 640-by-400 rectangle beginning at x=20, y=100
await page.screenshot({
  path: 'region.png',
  clip: { x: 20, y: 100, width: 640, height: 400 },
});

Screenshot options also include format-specific quality for lossy images and omitBackground for transparency. Quality does not apply to PNG. Review the options for the installed Puppeteer version in the ScreenshotOptions reference.

In a shared BrowserContext, page creation and closing wait for an in-progress screenshot to finish, while bringToFront() does not. If parallel capture jobs appear to pause around page creation or closure, account for that coordination behavior: Page API reference.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Generate PDFs with the intended CSS

page.pdf() renders using the CSS print media type by default. That is usually suitable for a printable document. If you need the page’s screen styles, emulate screen media before creating the PDF. Print output may adjust colors; the documentation points to -webkit-print-color-adjust when exact CSS colors are needed.

// Use print CSS, the default
await page.pdf({ path: 'print-layout.pdf' });

// Use screen CSS instead
await page.emulateMediaType('screen');
await page.pdf({ path: 'screen-layout.pdf' });

See the PDF API reference for the applicable release. Generating a PDF from a rendered page is different from navigating to a URL that serves an existing PDF: the Page navigation reference says headless shell does not support navigation to PDF documents. For that case, use an approach compatible with your browser mode rather than treating PDF navigation as ordinary HTML navigation.

Wait for the right condition

Choosing a navigation wait condition is a trade-off: waiting too little can capture before important content appears, while waiting for every network connection to stop can be unsuitable for pages that keep long-lived requests open. The example above uses networkidle2; for dynamic pages, wait for the particular content you need rather than relying only on a generic delay.

  • Use a Locator for an element you need to act on; it waits for presence and readiness for the action.
  • Use a selector-specific wait or Locator when a particular element signals that rendering is complete.
  • Use a delay only when the page’s behavior requires a known pause and there is no better observable condition.
  • Pair navigation-triggering actions with waitForNavigation() using Promise.all().

Common problems and fixes

The screenshot is blank or misses content

Check that navigation completed and that the target content has actually rendered. A full-page capture requires fullPage: true; a default capture is limited to the viewport. For content loaded asynchronously, wait for the relevant selector or state before capturing.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

page.$eval() throws

The selector did not match an element at the time of lookup. Wait for the target to appear or use a Locator for an action that should wait for the element to exist and be ready.

The script treats an error page as a successful navigation

A 404 or 500 response can still resolve from page.goto(). Check whether the returned response exists and inspect response.status() or response.ok() explicitly.

The click happened but the script did not wait for the next page

Register waitForNavigation() at the same time as the click with Promise.all(), so the wait is active before navigation begins.

The PDF looks different from the browser window

PDF generation defaults to print CSS. Call page.emulateMediaType('screen') before page.pdf() when screen styles are intended; use the print-color CSS guidance when print output changes colors.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Best Value
Sale
JavaScript and jQuery: Interactive Front-End Web Development
  • JavaScript Jquery
  • Introduces core programming concepts in JavaScript and jQuery
  • Uses clear descriptions, inspiring examples, and easy-to-follow diagrams

Navigation to an existing PDF fails in headless shell

The Page reference notes that headless shell does not support navigation to PDF documents. This is a browser-mode limitation, distinct from generating a PDF with page.pdf().

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Or skip the browser setup

If your task is to obtain an image or PDF from a URL rather than automate a browser session, ScreenshotNeo is a screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. Its capture process accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; those steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, with page verdict and billing information in response headers. AI agents can use its MCP server tools, including take_screenshot, get_page_info, and capture_pdf.

For example, using cURL:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo API documentation for setup and parameters. The free plan includes 1,000 screenshots per month with no card required; paid plans start at $5 for 3,000 shots. Sign up for ScreenshotNeo free.

Frequently Asked Questions

Does page.screenshot() capture the whole page by default?

No. Use fullPage: true for a full-page capture; the default is the viewport.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Can page.pdf() use screen styles?

Yes. Call page.emulateMediaType('screen') before page.pdf().

When should I use evaluateHandle() instead of evaluate()?

Use it when you need a retained handle to a page-side object rather than a returned value.

Quick Recap

SaleBestseller No. 1
HTML and CSS: Design and Build Websites
HTML and CSS: Design and Build Websites
HTML CSS Design and Build Web Sites; Comes with secure packaging; It can be a gift option
$14.18
SaleBestseller No. 2
Web Design with HTML, CSS, JavaScript and jQuery Set
Web Design with HTML, CSS, JavaScript and jQuery Set
Brand: Wiley; Set of 2 Volumes
$35.05
SaleBestseller No. 3
SaleBestseller No. 5
JavaScript and jQuery: Interactive Front-End Web Development
JavaScript and jQuery: Interactive Front-End Web Development
JavaScript Jquery; Introduces core programming concepts in JavaScript and jQuery; Uses clear descriptions, inspiring examples, and easy-to-follow diagrams
$22.78

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.