Making screenshots of the websites with Puppeteer is tricky. And I write that as somebody who has been working with Puppeteer for years.

Let’s play with Puppeteer on a set of screenshotting problems and see how it can solve them.

I am sharing a set of working Puppeteer examples. You can just copy them and adjust for your needs.

Meet Puppeteer

It is a Node library that interacts with browsers that support Chrome DevTools Protocol (CDP). It is not only Chrome and Chromium, but Firefox also has partial support of CDP.

The Chrome DevTools Protocol was developed to manage, debug and inspect Chromium and Chrome at the low level.

So, think of Puppeteer high-level API over Chrome DevTools Protocol which allows you to do everything in the browser that you can do manually:

Extract data from a SPA, submit a form, type text, perform end-to-end UI testing and other automation-related tasks.
Debug performance issues.
Run, debug and test Chrome Extensions.
Pre-render SPA to make a static site. But for Google SEO, it does not matter since Google renders JavaScript for every page nowadays.
And guess what? Make screenshots and PDFs of pages.

Generating screenshots with Puppeteer is the main focus of the post.

Lightweight option of Puppeteer

First of all, there are two versions of the library available: puppeteer-core and puppeteer. You should use puppeteer-core when you are going to manage browser instances by yourself, or you do not need it, otherwise stick to puppeteer.

Three simple examples that come to my mind with puppeteer-core:

You are using CDP from the extension, so you do not have to download Chrome or Chromium.
You want to use a different Chrome, Chromium, or Firefox build.
You have a running cluster of browsers or a separate browser instance on an other machine.

When you use puppeteer-core, you must ensure that you use a compatible browser version. But the puppeteer library downloads and runs a compatible version of Chromium instance for you, without any worries.

Practical Examples of using Puppeteer to take screenshots

Before starting to work with Puppeteer, let’s install it using npm:

npm i puppeteer

Simple screenshots with Puppeteer

To take a simple screenshot with Puppeteer and save it into the file, you can use the following code:

1
"use strict";
2

3
const puppeteer = require("puppeteer");
4
(async () => {
5
    const browser = await puppeteer.launch();
6
    try {
7
        const page = await browser.newPage();
8
        await page.goto("https://github.com");
9
        await page.screenshot({ path: "github.png" });
10
    } catch (e) {
11
        console.log(e);
12
    } finally {
13
        await browser.close();
14
    }
15
})();

The result is a screenshot of the GitHub website:

GitHub screenshot

You use the parameter path in Puppeteer to save the screenshot. And always close the browser to avoid resource leaking!

You can use our reliable and scalable screenshot API with myriad options to avoid the burden of setting up and managing Puppeteer.

High-resolution and Retina Displays

To avoid blurred images on a high-resolution display like Retina Display you can change the viewport properties width, height and deviceScaleFactor:

1
"use strict";
2

3
const puppeteer = require("puppeteer");
4

5
(async () => {
6
    const browser = await puppeteer.launch();
7

8
    try {
9
        const page = await browser.newPage();
10

11
        await page.setViewport({
12
            width: 2880, // default: 800
13
            height: 1800, // default: 600
14
            deviceScaleFactor: 2, // default: 1
15
        });
16

17
        await page.goto("https://apple.com");
18
        await page.screenshot({ path: "apple.com.png" });
19
    } catch (e) {
20
        console.log(e);
21
    } finally {
22
        await browser.close();
23
    }
24
})();

That’s called pixel-perfect screenshots.

Full-page screenshots

Puppeteer knows how to make screenshot of the scrollable page. Use fullPage option:

1
"use strict";
2

3
const puppeteer = require("puppeteer");
4

5
(async () => {
6
    const browser = await puppeteer.launch();
7

8
    try {
9
        const page = await browser.newPage();
10
        await page.goto("https://apple.com");
11
        await page.screenshot({ path: "apple.com.png", fullPage: true });
12
    } catch (e) {
13
        console.log(e);
14
    } finally {
15
        await browser.close();
16
    }
17
})();

But it won’t work good with lazy-loaded images. I wrote a brief guide on how to take full page screenshots with Puppeteer right.

Wait until the page is completely loaded

It is a good practice to wait until the page is completely loaded to make screenshot:

1
"use strict";
2

3
const puppeteer = require("puppeteer");
4

5
(async () => {
6
    const browser = await puppeteer.launch({});
7

8
    try {
9
        const page = await browser.newPage();
10

11
        await page.goto("https://apple.com/", {
12
            waitUntil: "networkidle2",
13
        });
14

15
        await page.screenshot({ path: "apple.com.png" });
16
    } catch (e) {
17
        console.log(e);
18
    } finally {
19
        await browser.close();
20
    }
21
})();

It is a little bit of magic, but networkidle2 event is heuristic to determine page load state. It works quite well for many real-world use cases.

But if you need to wait until some element is rendered and visible, you need to add Page.waitForSelector():

1
"use strict";
2

3
const puppeteer = require("puppeteer");
4

5
(async () => {
6
    const browser = await puppeteer.launch({});
7

8
    try {
9
        const page = await browser.newPage();
10

11
        await page.goto("https://example.com/", {
12
            waitUntil: "networkidle0",
13
        });
14

15
        const selector = "div";
16
        await page.waitForSelector(selector, {
17
            visible: true,
18
        });
19

20
        await page.screenshot({ path: "example.com.png" });
21
    } catch (e) {
22
        console.log(e);
23
    } finally {
24
        await browser.close();
25
    }
26
})();

You can also wait:

How to take a screenshot of the page area

To take the screenshot of the page area, use the clip option:

1
"use strict";
2

3
const puppeteer = require("puppeteer");
4

5
(async () => {
6
    const browser = await puppeteer.launch();
7

8
    try {
9
        const page = await browser.newPage();
10
        await page.goto("https://apple.com");
11
        await page.screenshot({
12
            path: "apple.com.png",
13
            clip: {
14
                x: 100,
15
                y: 100,
16
                width: 800,
17
                height: 800,
18
            },
19
        });
20
    } catch (e) {
21
        console.log(e);
22
    } finally {
23
        await browser.close();
24
    }
25
})();

But if you need to take a screenshot of the element, there is a better approach.

A screenshot of the specific element

Puppeteer allows to take the screenshot of any element on the web page:

1
"use strict";
2

3
const puppeteer = require("puppeteer");
4

5
(async () => {
6
    const browser = await puppeteer.launch();
7

8
    try {
9
        const page = await browser.newPage();
10
        await page.goto("https://example.com");
11

12
        const selector = "body > div:first-child";
13
        await page.waitForSelector(selector);
14
        const element = await page.$(selector);
15

16
        await element.screenshot({
17
            path: "example.com.png",
18
        });
19
    } catch (e) {
20
        console.log(e);
21
    } finally {
22
        await browser.close();
23
    }
24
})();

As you see, it is essential to make sure that the element is ready.

In ScreenshotOne screenshot API, you can take the screenshot of the element by specifying the selector parameter.

Screenshots with transparent background

Puppeteer provides a useful option to omit the background of the site. Just set omitBackground to true:

1
"use strict";
2

3
const puppeteer = require("puppeteer");
4

5
(async () => {
6
    const browser = await puppeteer.launch();
7

8
    try {
9
        const page = await browser.newPage();
10
        await page.goto("https://example.com");
11

12
        await page.screenshot({
13
            path: "example.com.png",
14
            omitBackground: true,
15
        });
16
    } catch (e) {
17
        console.log(e);
18
    } finally {
19
        await browser.close();
20
    }
21
})();

Have you run the code? If yes, you spotted that the screenshot does not have a transparent background. It happens because omitting background works only for elements with transparent background.

So if your target site does not have a transparent background and you want to force it, you can use JavaScript to accomplish the task. Change the background of the body in the evaluate function:

1
"use strict";
2

3
const puppeteer = require("puppeteer");
4

5
(async () => {
6
    const browser = await puppeteer.launch();
7

8
    try {
9
        const page = await browser.newPage();
10
        await page.goto("https://example.com");
11

12
        await page.evaluate(() => {
13
            document.body.style.background = "transparent";
14
        });
15

16
        await page.screenshot({
17
            path: "example.com.png",
18
            omitBackground: true,
19
        });
20
    } catch (e) {
21
        console.log(e);
22
    } finally {
23
        await browser.close();
24
    }
25
})();

Screenshot as Base64

I also wrote about rendering PNG, JPEG, and WebP in Base64 encoding with Puppeetter.

You build Puppeteer as a service and do not want to store screenshot files. You can choose to return the screenshot in Base64 encoding format:

1
"use strict";
2

3
const puppeteer = require("puppeteer");
4

5
(async () => {
6
    const browser = await puppeteer.launch({});
7

8
    try {
9
        const page = await browser.newPage();
10
        await page.goto("https://example.com/");
11

12
        const base64 = await page.screenshot({ encoding: "base64" });
13
        console.log(base64);
14
    } catch (e) {
15
        console.log(e);
16
    } finally {
17
        await browser.close();
18
    }
19
})();

You will receive a string that you can share with another service or even store somewhere.

Generate JPEG or WebP instead of PNG

It is super easy to generate JPEG or WebP instead of PNG:

1
"use strict";
2

3
const puppeteer = require("puppeteer");
4
(async () => {
5
    const browser = await puppeteer.launch();
6
    try {
7
        const page = await browser.newPage();
8
        await page.goto("https://example.com");
9
        await page.screenshot({
10
            path: "example.jpg",
11
            type: "jpeg",
12
            quality: 100,
13
        });
14
    } catch (e) {
15
        console.log(e);
16
    } finally {
17
        await browser.close();
18
    }
19
})();

When you generate JPEG or WebP, you can specify the quality of the screenshot.

If JPEG, WebP or PNG is not enough for you, you can render URL or HTML in GIF, JP2, TIFF, AVIF or HEIF format with Puppeetter.

Blocking ads and trackers when using Puppeteer

In our screenshot API, you can block ads by setting blockAds=true.

I do not use any ad blocking extension because life is tough, and everybody needs some way to earn money. If I can help sites sustain and survive by non-blocking the ads, I will do it.

But when you test your site or your customer site, you might need to block the ads. There are 2 ways to do it:

Intercept and block request that load ad into the site.
Use an extension that is optimized exactly to solve this problem.

The first one is tricky and highly depends on the site you are taking screenshots of. But using an extension is a highly-scalable approach that works out of the box.

Install puppeteer-extra and puppeteer-extra-plugin-adblocker in addition to puppeteer package:

npm i puppeteer-extra puppeteer-extra-plugin-adblocker

And then use it:

1
"use strict";
2

3
const puppeteer = require("puppeteer-extra");
4

5
const AdblockerPlugin = require("puppeteer-extra-plugin-adblocker");
6
puppeteer.use(AdblockerPlugin());
7

8
(async () => {
9
    const browser = await puppeteer.launch();
10

11
    try {
12
        const page = await browser.newPage(); // ads are blocked automatically
13

14
        await page.goto("https://www.example.com");
15

16
        await page.screenshot({
17
            path: "example.com.png",
18
            fullPage: true,
19
        });
20
    } catch (e) {
21
        console.log(e);
22
    } finally {
23
        await browser.close();
24
    }
25
})();

Most pages include ads and trackers, which consume a lot of bandwidth and take a long time to load. Because fewer requests are made, and less JavaScript is performed when advertisements and trackers are blocked, pages load substantially quicker.

To take screenshots faster you might block trackers. It will help to speed up rendering. The ad blocking plugin can help us with this issue.

Just set blockTrackers to true when initializing the plugin:

1
puppeteer.use(
2
    AdblockerPlugin({
3
        blockTrackers: true, // default: false
4
    })
5
);

If you need to block only trackers, but do not block ads, just use request interceptor.

Preventing Puppeteer detection

Some sites might block your Puppeteer script because of the user agent, and it is easy to fix:

1
"use strict";
2

3
const puppeteer = require("puppeteer");
4

5
(async () => {
6
    const options = {
7
        args: [
8
            '--user-agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36"',
9
        ],
10
        headless: true,
11
    };
12

13
    const browser = await puppeteer.launch(options);
14
    try {
15
        const page = await browser.newPage();
16
        await page.goto("https://www.example.com");
17

18
        await page.screenshot({
19
            path: "example.com.png",
20
            fullPage: true,
21
        });
22
    } catch (e) {
23
        console.log(e);
24
    } finally {
25
        await browser.close();
26
    }
27
})();

There are also many other hacks to ensure that Puppeteer is not detected, but you can save time by using the ready puppeteer-extra-plugin-stealth plugin for the stealth mode. Install it in addition to puppeteer package:

npm i puppeteer-extra puppeteer-extra-plugin-stealth

And then use:

1
"use strict";
2

3
const puppeteer = require("puppeteer-extra");
4

5
const StealthPlugin = require("puppeteer-extra-plugin-stealth");
6
puppeteer.use(StealthPlugin());
7

8
(async () => {
9
    const browser = await puppeteer.launch();
10

11
    try {
12
        const page = await browser.newPage();
13
        await page.evaluateOnNewDocument(() => {
14
            const newProto = navigator.__proto__;
15
            delete newProto.webdriver;
16
            navigator.__proto__ = newProto;
17
        });
18

19
        await page.goto("https://bot.sannysoft.com");
20
        await page.waitForTimeout(5000);
21
        await page.screenshot({ path: "stealth.png", fullPage: true });
22
    } catch (e) {
23
        console.log(e);
24
    } finally {
25
        await browser.close();
26
    }
27
})();

Important! As you see, I remove the webdriver property since the stealth plugin misses this hack and by using webdriver property usage of the Puppeteer can be detected.

Using basic access authentication with Puppeteer

If your page is protected by HTTP basic access authentication, the only thing you need to do is to specify username and password before loading and taking the screenshot of the page:

1
"use strict";
2

3
const puppeteer = require("puppeteer");
4

5
(async () => {
6
    const browser = await puppeteer.launch();
7

8
    try {
9
        const page = await browser.newPage();
10

11
        await page.authenticate({
12
            username: "YOUR_BASIC_AUTH_USERNAME",
13
            password: "YOUR_BASIC_AUTH_PASSWORD",
14
        });
15

16
        await page.goto("https://example.com");
17
        await page.screenshot({ path: "example.png" });
18
    } catch (e) {
19
        console.log(e);
20
    } finally {
21
        await browser.close();
22
    }
23
})();

Support of emojis, Japanese, Chinese and other non-Latin languages in Puppeteer

Our screenshot API supports emojis out of the box.

If you run Puppeteer in OS without emojis support, you need to install OS-wide fonts to support emojis. The same can happen with non-English characters like Chinese, Japanese, Korean, Arabic, Hebrew, etc.

To get Puppeteer to render emojis, you can use Noto Fonts published under SIL Open Font License (OFL) v1.1.

You need to search and how to install fonts for your host OS.

More recipes on using Puppeteer

You also might find useful:

Puppeteer Alternatives

There are a lot more, but the most popular two are:

The oldest alternative to make screenshots is using the Selenium WebDriver protocol.
The second one is to render screenshots with Playwright, and it is a good one. It is the competitor to the Puppeteer.
If you consider only rendering screenshots, ScreenshotOne is the best Puppeteer alternative.

Playwright and Puppeteer have compatible API, but Playwright supports more browsers. So, if you must take screenshots in different browsers, prefer to use Playwright. By the way, top contributors of the Puppeteer work on Playwright. But the library is still considered new.

Conclusion

I posted a lot of Puppeteer examples, and I hope I helped you solve your screenshot problems with Puppeteer.

As you see you can go really far with Puppeteer. But if only need to take screenshots, consider using one of the best Puppeteer alternatives—our screenshot API.

Thank you for reading! And have a nice day 👋

Written by

Updated on