How to Fix Playwright Screenshots That Are Too Tall or Clipped

When a Playwright screenshot is too tall or clipped, first identify which dimension is wrong: the capture target, the crop rectangle, or the pixel scale. For the whole scrollable document, use fullPage: true. For a viewport screenshot, leave it off. Remove or correct an unintended clip, and use scale: 'css' when you want output dimensions measured in CSS pixels.

These settings solve different problems. fullPage changes how much of the page is captured, clip sets an explicit rectangle, and scale changes the image’s pixel density. Changing scale will not reveal content outside the capture area.

1. Choose the screenshot target

Playwright’s default page.screenshot() captures the current viewport. A full-page screenshot captures the full scrollable page, as if it were displayed on a very tall screen. Use the mode that matches the image you need; full-page output can be much taller than a viewport screenshot by design.

Desired result	Use	What to check
What a user can see in the current browser window	`page.screenshot()`	Set a known viewport size before navigation.
The full scrollable document	`page.screenshot({ fullPage: true })`	Check whether long-page output is expected.
One element and its bounds	`locator.screenshot()`	The image follows the element’s bounds; a scrollable element shows its currently scrolled content.
A fixed crop	`page.screenshot({ clip: { ... } })`	Verify the clip’s x, y, width, and height.

See the official Playwright Screenshots guide and the Page screenshot API for the options supported by your installed version.

2. Run a minimal Playwright screenshot

This JavaScript example uses Playwright’s test runner, sets the viewport explicitly, and writes both viewport and full-page captures. Save it as tests/screenshot.spec.js.

const { test } = require('@playwright/test');

test('capture viewport and full page', async ({ page }) => {
  await page.setViewportSize({ width: 1280, height: 800 });
  await page.goto('https://example.com', { waitUntil: 'networkidle' });

  // Viewport-sized screenshot: the default target.
  await page.screenshot({ path: 'artifacts/viewport.png' });

  // Entire scrollable document.
  await page.screenshot({
    path: 'artifacts/full-page.png',
    fullPage: true,
    scale: 'css',
  });
});

To run it in a fresh directory:

npm init -y
npm install --save-dev @playwright/test
npx playwright install chromium
mkdir -p artifacts tests
# Save the example as tests/screenshot.spec.js
npx playwright test tests/screenshot.spec.js

If the page relies on client-side rendering, wait for a page-specific ready condition before capturing. For example, after navigation you can wait for a known content selector:

await page.goto('https://example.com');
await page.locator('main article').waitFor({ state: 'visible' });
await page.screenshot({ path: 'artifacts/ready.png', fullPage: true });

Replace the example URL and selector with the page and content your script needs. Waiting for a selector is often more precise than assuming that a fixed delay means the page is ready.

3. Fix screenshots that are too tall

Check whether you enabled full-page capture

If the image includes content below the fold and you wanted only the visible browser window, remove fullPage: true. A full-page screenshot is supposed to extend beyond the viewport.

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

// Full scrollable document
await page.screenshot({ path: 'document.png', fullPage: true });

Check output scale if the pixel dimensions are unexpectedly large

The scale option controls raster dimensions. With scale: 'css', output uses one image pixel per CSS pixel. With scale: 'device', output uses device pixels, so high-DPI settings can produce larger images. Scale changes pixel density; it does not change the selected page area.

await page.screenshot({
  path: 'css-pixel-size.png',
  fullPage: true,
  scale: 'css',
});

Compare the PNG’s pixel dimensions with the page’s CSS dimensions. If the image is roughly multiplied in both dimensions, inspect device scale and the viewport or device configuration before changing page layout.

4. Fix screenshots that are clipped

Inspect the clip rectangle

A clip option explicitly limits the capture to a rectangle defined by x, y, width, and height. Remove it if you want the regular viewport or full-page target. If you do want a crop, make its coordinates and dimensions large enough for the intended region.

// Intentional crop: 1200 by 800 CSS pixels, starting at the page origin
await page.screenshot({
  path: 'crop.png',
  clip: { x: 0, y: 0, width: 1200, height: 800 },
});

A clip is a fixed rectangle, so it may be wrong if the viewport, content position, or page layout changes. For the entire document, use fullPage: true instead of trying to approximate the page with a large clip.

Check whether you captured an element instead of the page

An element screenshot is bounded by the selected element. If the target is a scrollable element, Playwright captures the content currently scrolled into view in that element; it does not automatically stitch all of that element’s internal scroll positions into one image. If you need the full document, use page.screenshot({ fullPage: true }). If you need a particular component, make sure your locator selects the intended element and understand that the result follows its bounds.

// Component capture follows this element's bounds
await page.locator('main').screenshot({ path: 'main.png' });

5. Diagnose the geometry in a repeatable order

State the intended target. Decide whether you need the viewport, the full document, or one element.
Read the screenshot call. Look for fullPage, clip, and whether the call is on page or a locator.
Set the viewport explicitly. This makes viewport captures comparable across runs and helps explain dimensions.
Check scale. Use CSS scale when you want one output pixel per CSS pixel; use device scale when device-pixel output is desired.
Inspect the file’s pixel dimensions. Compare width and height to the expected viewport or document dimensions.
Only then inspect page behavior. If the geometry is right but content is absent, investigate loading, layout, sticky elements, and page-specific CSS.

For visual tests, geometry and repeatability are separate concerns. Playwright’s screenshot assertions wait for consecutive screenshots to match before comparing them. The visual comparison guide also documents stylePath for applying styles that help make screenshots repeatable. These tools can reduce visual noise; they do not diagnose why a particular site’s layout is clipped.

See Playwright’s visual comparisons guide for screenshot assertions and stabilization options.

6. Troubleshooting common cases

Symptom	Likely cause	Fix
Screenshot includes the whole long page, but only the viewport was wanted	`fullPage: true` is enabled.	Remove it and capture the page viewport.
Only a rectangle or top portion appears	An explicit `clip` is too small or starts at the wrong coordinates.	Remove the clip, or correct its x/y/width/height.
Bottom of the document is missing	The call captures the viewport, an element, or a clipped region rather than the full document.	Use page-level `fullPage: true`; check locator and clip usage.
A scrollable panel does not show all its internal content	The element screenshot shows the panel’s currently scrolled content.	Capture the document if that is the target, or scroll the panel to the needed content before taking the element screenshot.
Image dimensions are much larger than expected	Device-pixel scale or a larger viewport/device configuration.	Inspect viewport and device settings; use `scale: 'css'` if CSS-pixel dimensions are wanted.
Screenshot differs across runs or looks partly rendered	The page may still be changing or content may load asynchronously.	Wait for a page-specific selector or stable state; use screenshot assertions for visual tests. Inspect the page itself for layout behavior.
Full-page capture still omits content	The page may use internal scrolling, lazy loading, or page-specific rendering behavior.	Determine whether the missing content belongs to the document or a nested scroller. Wait for the relevant content and inspect the page’s CSS and loading behavior.

7. Performance, reliability, and cost

Full-page images can have many more pixels than viewport images, especially on long documents or at device scale. That increases image file size and can make capture and downstream image processing heavier. Use viewport capture for viewport-sized checks, CSS scale when device pixels are unnecessary, and element capture when the component itself is the desired artifact.

For reliable runs, use a consistent viewport, wait for the content you need, and avoid relying on arbitrary delays when a selector or page state is available. When a page contains lazy-loaded content, confirm that the content has actually been rendered before treating a missing region as a screenshot geometry problem. Playwright’s screenshot API documentation describes the available capture options; options can vary by installed version, so consult the API matching your version.

Running Playwright yourself has no per-screenshot API charge from ScreenshotNeo, but you are responsible for the browser runtime and infrastructure you use. If you need a hosted screenshot endpoint instead, ScreenshotNeo’s published plans are Free for 1,000 shots per month, Starter $5 for 3,000, Growth $15 for 15,000, Pro $39 for 60,000, Scale $99 for 250,000, and Business $249 for 1,000,000; yearly billing gives two months free. Every feature is on every plan.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server from ScreenshotNeo. One GET request takes a URL and returns a PNG, JPEG, WebP, or PDF. Its API options include full-page capture, element capture, viewport and device presets, and output scale. See the ScreenshotNeo API documentation.

cURL:

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

Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await import('node:fs/promises').then(({ writeFile }) => writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));

ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; those cleanup steps can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers say which page verdict and billing outcome applied. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The Free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000.

FAQ

Does `fullPage: true` change the browser viewport?

It requests a screenshot of the full scrollable page. It is a capture option, distinct from choosing a viewport size for regular viewport screenshots.

Should I use `scale: 'css'` or `scale: 'device'`?

Choose CSS scale for one output pixel per CSS pixel. Choose device scale when you want output in device pixels and accept that high-DPI settings can make the image larger.

Can an element screenshot capture all content inside a scrollable panel?

It shows the element’s currently scrolled content. To capture a different region, scroll that panel first; to capture the whole document, use a page screenshot with fullPage: true.

Will screenshot assertions fix a clipped capture?

No. Assertions help wait for stable images in visual comparisons. Diagnose the capture target, clip rectangle, and scale to fix geometry.