How to Capture Website Screenshots from Node.js
A screenshot request in Node.js can return three different kinds of image: the visible viewport, the entire scrollable page, or one HTML element chosen by a CSS selector.
The capture mode is set with request parameters, and the viewport size can be adjusted so the visible-area image matches the dimensions you need. This guide explains each mode, the parameters involved, and how to choose between them.
Three capture modes and the parameters that select them
Every screenshot request starts with the same client call. What changes is the parameter you send:
- Visible viewport: set
screenshottotrueorfalse. This captures only the portion of the page currently visible in the browser window. - Full page: set
screenshot_full_pagetotrueorfalse. This captures the whole page, including content below the initial viewport. - Single element: set
screenshot_selectorto the CSS selector of the element you want. This captures just that element.
The default viewport is 1920px wide and 1080px tall. To change it, add window_width and window_height to the request. For example, setting window_width to 1280 and window_height to 720 produces a visible-area image of 1280x720 pixels.
Which mode should you use?
Use this checklist before writing the request:
- Do you need only what a visitor sees without scrolling? Use
screenshotwith the default or custom viewport. - Do you need the entire page, including content far below the fold? Use
screenshot_full_page. - Do you need one specific component, such as a footer, card, or chart? Use
screenshot_selectorwith a CSS selector that uniquely identifies it. - Does the image need a particular width and height? Add
window_widthandwindow_height; otherwise the default 1920x1080 viewport applies to visible-area captures.
A common mistake is to expect a full-page result from the basic screenshot parameter. The visible-area capture stops at the viewport boundary, so blog posts and footers below that line will not appear. If those parts matter, switch to screenshot_full_page.
Parameter reference
The table below summarizes each request parameter, its accepted value, and the effect on the returned image.
Worked example: capturing a footer element
Suppose you want only the footer of a page. You set screenshot_selector to footer in the request parameters. The client returns an image containing just that element rather than the surrounding page. The same approach works for any HTML element as long as the CSS selector matches it.
For a full-page capture, replace the selector with screenshot_full_page set to true. For a visible-area capture at a custom size, use screenshot set to true together with window_width and window_height.
| Parameter | Accepted value | Effect |
|---|---|---|
| screenshot | true or false | Captures the visible portion of the page |
| screenshot_full_page | true or false | Captures the entire page |
| screenshot_selector | CSS selector of the element | Captures only the matched element |
| window_width | pixel value (e.g. 1280) | Sets the viewport width |
| window_height | pixel value (e.g. 720) | Sets the viewport height |
Default viewport is 1920px by 1080px unless window_width and window_height are supplied.
Frequently asked questions
What is the default screenshot size?
The default viewport is 1920px wide and 1080px tall. A visible-area capture therefore returns an image of that size unless you change window_width and window_height.
Why does my screenshot miss the footer?
The basic screenshot parameter captures only the visible viewport. Content below that boundary, such as blog posts or a footer, is outside the image. Use screenshot_full_page to include the whole page, or screenshot_selector to target the footer directly.
Can I capture a single HTML element?
Yes. Set screenshot_selector to the CSS selector of the element you want, for example footer. The returned image contains only that element.