BrowserCat Screenshots Have the Wrong Dimensions: How to Fix Them

If a BrowserCat screenshot has the wrong dimensions, check three independent settings in the automation client: the page’s CSS viewport, the screenshot’s pixel scale, and whether you captured the visible viewport or the full page. BrowserCat documents connecting through standard Playwright, Puppeteer, and CDP-compatible clients; the reviewed documentation does not establish a separate BrowserCat-only screenshot sizing switch. Set the dimensions through your automation client, then compare the browser’s measurements with the saved image’s pixel dimensions. BrowserCat’s documentation describes its browser automation support; the exact screenshot options below are Playwright options. [BrowserCat documentation] [Playwright screenshots]

What controls screenshot dimensions?

Two different kinds of dimensions are easy to confuse:

CSS viewport dimensions determine the space available for page layout. They affect responsive breakpoints and the values reported by window.innerWidth and window.innerHeight.
Output pixel dimensions describe the raster image saved to disk. Screenshot scale and device pixel ratio (DPR) can make these differ from the CSS viewport.

Capture area is a separate choice. A viewport screenshot captures the currently visible area; a full-page screenshot includes the scrollable document and can therefore have a much greater height. Playwright also supports a clip rectangle to capture a specific region. [Playwright screenshot options] [MDN: devicePixelRatio]

Control	What it affects	Where to inspect it
Viewport width and height	CSS layout area and responsive behavior	Browser context and `innerWidth`/`innerHeight`
Device scale factor and screenshot scale	Raster pixels written per CSS pixel	Context configuration, `devicePixelRatio`, and screenshot options
Viewport versus full-page capture	Captured area, especially output height	`fullPage`
Clip rectangle	Captured bounds and output dimensions	`clip`

Fix it in a Playwright script connected to BrowserCat

Set the viewport and device scale factor when creating the browser context or page, before navigating. Then choose the capture mode and screenshot scale explicitly. This example uses Playwright’s documented options; adapt the connection setup to your BrowserCat account and the Playwright connection method in your project.

const page = await browser.newPage({
  viewport: { width: 1280, height: 800 },
  deviceScaleFactor: 1,
});

await page.goto('https://example.com', { waitUntil: 'load' });

const measurements = await page.evaluate(() => ({
  innerWidth: window.innerWidth,
  innerHeight: window.innerHeight,
  devicePixelRatio: window.devicePixelRatio,
  documentWidth: document.documentElement.scrollWidth,
  documentHeight: document.documentElement.scrollHeight,
}));
console.log('Page dimensions:', measurements);

await page.screenshot({
  path: 'capture.png',
  fullPage: false,
  scale: 'css',
});

With a 1280 × 800 CSS viewport and scale: 'css', the intended output is one raster pixel per CSS pixel for a viewport capture. Check the actual saved file rather than assuming it matches: page content, clipping, capture mode, and the installed Playwright version’s supported options can affect the result. Playwright’s scale option accepts 'css' or 'device'; choose device scale when you specifically want the output density to follow device pixels. [Playwright page.screenshot() reference]

Capture the full scrollable page

Set fullPage: true when the output should include the entire page. Its width follows the page’s rendered content and its height follows the scrollable document, rather than staying at the viewport height. If you need a fixed-size image, use viewport capture or an explicit clip instead.

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

Capture a specific region

Use clip to capture a rectangle in page coordinates. Set its width and height to the desired region; the screenshot’s raster size still depends on scale. Avoid combining a clip and full-page capture unless you have checked the behavior supported by your installed Playwright version.

await page.screenshot({
  path: 'region.png',
  clip: { x: 0, y: 0, width: 640, height: 400 },
  scale: 'css',
});

Check the image file’s real dimensions

Image previews can be scaled to fit a window, so inspect the file itself. One portable option is Python with Pillow:

from PIL import Image

with Image.open("capture.png") as image:
    print(image.size)  # (width, height) in pixels

Install Pillow in your environment if it is not already available. Alternatively, use an image viewer or file-inspection tool that reports pixel dimensions.

Step-by-step diagnosis

Read the saved file’s pixel width and height. Record those values; do not use the preview window’s display size.
Log the intended viewport. Check the context or page configuration that was active for this capture.
Measure the page in the same session. Record innerWidth, innerHeight, devicePixelRatio, and document scroll dimensions after navigation. The diagnostic code above logs these values.
Set the intended viewport before navigation. A different CSS width can trigger a different responsive layout even if the final image is later resized.
Choose scale deliberately. Use scale: 'css' for CSS-pixel output or scale: 'device' when device-pixel density is wanted. Check the DPR as well.
Choose the capture area deliberately. Use fullPage: false for the visible viewport and fullPage: true for the scrollable document. Add clip when you need a defined region.
Capture again and compare. Keep the target URL, viewport, DPR, scale, and capture mode constant while diagnosing; otherwise multiple changes can obscure the cause.

Common symptoms and fixes

Symptom	Likely cause	Fix
Image is wider or narrower than expected	Viewport width or clip rectangle is different from the target	Set the context viewport width explicitly; inspect `innerWidth` and the clip bounds.
Image is taller than the viewport	`fullPage` is enabled, or the expected viewport height is wrong	Use `fullPage: false` for the visible area. For full-page output, expect document height.
Pixel dimensions are a multiple of the expected CSS dimensions	Device scale or DPR changes raster output	Log `devicePixelRatio` and set `scale` explicitly. Use CSS scale for one output pixel per CSS pixel.
Page has the wrong responsive layout	The CSS viewport width at render time differs from the intended width	Set the viewport before navigation and verify `innerWidth` in that session.
Output is unexpectedly cropped	A clip rectangle restricts the capture, or viewport capture excludes offscreen content	Review `clip`; use full-page capture if offscreen document content is required.
Logged dimensions look right but the file does not	Browser CSS dimensions were mistaken for raster pixels, or a different capture ran	Log the measurements and save path for the same capture; inspect the resulting image file directly.

Other clients and request options

BrowserCat supports Playwright, Puppeteer, and CDP-compatible clients. The key is to set the viewport and capture options in the client you are using. The reviewed BrowserCat materials establish those integration paths but do not document a separate BrowserCat-specific width/height parameter. Avoid adding guessed query parameters to a BrowserCat endpoint; consult the current documentation for your connection details and use the relevant automation library’s API. [BrowserCat documentation]

This issue is usually about the browser session and screenshot options, so cURL alone is not a substitute for configuring that session. If your own service accepts a URL and offers screenshot controls, use its documented viewport and scale options rather than assuming BrowserCat settings transfer to it.

Performance, reliability, and cost

Performance: Viewport capture generally involves less page area than full-page capture. Full-page captures can take longer or use more memory on very long documents, so request the smallest area that meets your need.
Reliability: Set the viewport before navigation, wait for the page state your use case requires, and record measurements from the same session as the screenshot. Dynamic pages may change their document height after load, so capture after the relevant content has appeared.
Cost: The supplied BrowserCat research does not specify pricing or per-screenshot cost. Check BrowserCat’s current plan terms for your account rather than relying on an assumed rate.

Or skip the browser setup

For a URL-to-image request, ScreenshotNeo provides a screenshot API and MCP server. Its API can return PNG, JPEG, WebP, or PDF, and its viewport and capture options let you request the output you need. See the ScreenshotNeo API documentation for the available parameters. This example requests a screenshot of a Stripe page:

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

ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

Does BrowserCat have a special setting for screenshot width and height?

The reviewed BrowserCat sources describe standard automation clients and do not establish a BrowserCat-only screenshot sizing switch. Configure the viewport and screenshot options through your Playwright, Puppeteer, or CDP workflow.

Why does a 1280-pixel viewport produce a larger image?

The viewport is measured in CSS pixels; device scale can write multiple raster pixels for each CSS pixel. Check the DPR and set the screenshot scale explicitly.

Will setting the viewport resize the page content?

It changes the browser’s CSS layout area and can trigger responsive rules. It does not mean the saved image will have those same pixel dimensions unless the screenshot scale and capture area align with that expectation.

How do I get a fixed-height screenshot of a long page?

Use a viewport screenshot for a fixed visible height, or capture a defined clip. Full-page mode follows the document’s scrollable height.