Take a screenshot "from the surface" in Puppeteer and Chrome DevTools Protocol

Let's talk about the fromSurface parameter introduced in Chrome DevTools Protocol which will soon be supported by Puppeteer or even supported now at the time when you are reading the post.

Written by

Dmytro Krasun

Published on

When fromSurface is set to true, captures screenshot from the surface rather than the view. When it is set to false, works only in headful mode and ignores page viewport (but not browser window’s bounds). Defaults to true.

The option doesn’t make much sense when using headless mode. But to understand how it works, let’s execute the next code in the headful mode:

'use strict';
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({headless: false});
try {
const page = await browser.newPage();
await page.setViewport({width: 1920, height: 1280});
await page.goto('https://screenshotone.com');
await page.screenshot({ path: 'from_surface_false.png', fromSurface: false});
} catch (e) {
console.log(e)
} finally {
await browser.close();
}
})();

The window is opened, and it is size is limited by the default window size, but the viewport size is different, so that’s what you would see if you run the code:

A window

So, when fromSurface is set to false, that’s how the screenshot will look like:

A screenshot from the surface

By the way, there is a few related articles you might be interested in:

  1. Capture beyond viewport in Puppeteer and Chrome DevTools Protocol.
  2. Optimize for speed when rendering screenshots in Puppeteer and Chrome DevTools Protocol.
  3. A complete guide on how to take full page screenshots with Puppeteer, Playwright or Selenium.

Read more Puppeteer guides

Interviews, tips, guides, industry best practices, and news.

View all posts
How to take website screenshots in Python

How to take website screenshots in Python

With Python, you can take website screenshots in multiple ways. But the best way to do it depends solely on your needs and your use case. Let's quickly examine all the options.

Read more
3 best screenshot APIs in 2025

3 best screenshot APIs in 2025

The truth is, that there is no single best screenshot API that fits everyone. But some APIs stand out and shine when compared to others. Also, it depends on your use case and needs which must be included in considering what API to use.

Read more

Automate website screenshots

Exhaustive documentation, ready SDKs, no-code tools, and other automation to help you render website screenshots and outsource all the boring work related to that to us.