How to Set a Custom Viewport Size in BrowserCat Screenshots
Set Playwright’s viewport before capturing a BrowserCat screenshot. Learn how viewport dimensions affect layout, when to use full-page capture, and how to troubleshoot common issues.
To set a custom viewport size for a BrowserCat screenshot, use Playwright’s page.setViewportSize() before calling page.screenshot(). Width and height are in CSS pixels:
await page.setViewportSize({ width: 390, height: 844 });
await page.screenshot({ path: 'mobile.png' });This changes the browser’s layout viewport, so responsive breakpoints and page reflow can change. It does not make the screenshot full-page; add fullPage: true if you want the entire document. BrowserCat’s example dimensions of 2000 × 1000 are illustrative, not a documented service limit. [BrowserCat Playwright cheatsheet]
Complete BrowserCat workflow
Connect to BrowserCat with a supported Playwright client, navigate to the target page, set the viewport, and capture. BrowserCat’s quick start describes its cloud Chromium workflow and recommends Playwright for getting started. [BrowserCat quick start]
const browser = await connectToBrowserCat(); // Use BrowserCat's documented connection setup
const page = await browser.newPage();
await page.goto('https://example.com');
await page.setViewportSize({ width: 390, height: 844 });
await page.screenshot({ path: 'mobile.png' });
await browser.close();connectToBrowserCat() represents the connection setup for your BrowserCat account and client; use the current connection code from the BrowserCat quick start. The viewport and screenshot calls are the relevant Playwright operations.
Choose dimensions for the layout you need
Pass integer width and height values in CSS pixels. Set the viewport before capture so the page renders at the intended layout size. For example:
await page.setViewportSize({ width: 1440, height: 900 }); // desktop
await page.screenshot({ path: 'desktop.png' });
await page.setViewportSize({ width: 390, height: 844 }); // narrow viewport
await page.screenshot({ path: 'narrow.png' });These are example sizes, not BrowserCat limits or guarantees about a particular device. The cited BrowserCat documentation does not state minimum or maximum viewport dimensions, nor does it specify how device scale affects physical output pixels. Viewport CSS pixels and final image pixels should therefore not be assumed to be identical in every configuration. [BrowserCat Playwright cheatsheet]
Viewport size versus screenshot extent
Viewport dimensions control the browser’s layout area. Screenshot options control what portion of the page is saved. BrowserCat’s cheatsheet demonstrates viewport, full-page, and element captures as separate choices. [BrowserCat Playwright cheatsheet]
| Goal | Playwright capture | What it captures |
|---|---|---|
| Visible area at the selected viewport | await page.screenshot() |
The current viewport |
| Entire document | await page.screenshot({ fullPage: true }) |
The full page, rather than only the visible viewport |
| One element | await page.locator('h1').screenshot() |
The selected element |
For example, to capture a whole page laid out at a mobile width:
await page.setViewportSize({ width: 390, height: 844 });
await page.screenshot({ path: 'mobile-full.png', fullPage: true });The viewport still affects the layout; fullPage changes the capture extent. It does not mean “use a mobile device” by itself.
Other ways to request a screenshot
If you already have a BrowserCat Playwright page, the viewport setting is made on that page before capture. For other languages and tools, use the BrowserCat documentation for supported client setup and APIs; the research sources establish the JavaScript/TypeScript Playwright workflow, not equivalent BrowserCat examples in cURL, Python, or Node.js fetch. [BrowserCat Playwright cheatsheet]
cURL
cURL does not operate a Playwright page or set its viewport. Use BrowserCat’s documented API, if available for your account and workflow, rather than assuming a viewport parameter.
Python
The cited BrowserCat material does not provide a Python example for changing the viewport. The operation documented here is Playwright’s JavaScript/TypeScript page.setViewportSize().
Node.js
The complete workflow above uses Node.js syntax for the Playwright page methods. BrowserCat’s quick start provides the service connection setup. [BrowserCat quick start]
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| The page still looks like desktop | The viewport was set after the screenshot, or a desktop breakpoint still applies at that width. | Call setViewportSize() before capture and choose the width that should trigger the intended responsive layout. |
| The screenshot only shows the top of the page | A regular screenshot captures the current viewport. | Pass { fullPage: true } when capturing the entire document. |
| The screenshot dimensions differ from the viewport values | Viewport values describe CSS pixels; output scaling may affect image pixels. | Check the image dimensions and the browser/device scale settings in your setup. The cited BrowserCat material does not define scaling behavior. |
| Viewport call fails or has no effect | The object may not be a Playwright page, or the code may be using an unsupported client or ordering. | Confirm the BrowserCat connection and page creation follow the current quick start, then set the size on that page before capture. |
| The selected element capture is missing | The locator may not match the page element. | Check the selector and use the element screenshot method only when you want that element rather than the whole viewport. |
Performance, reliability, and cost considerations
A custom viewport affects page layout and the resulting capture dimensions; the sources supplied for this guide do not publish BrowserCat performance figures, pricing, viewport limits, or reliability guarantees. Avoid treating the 2000 × 1000 example as a maximum. For repeatable captures, use the same viewport values and capture mode each time, and keep the order explicit: navigate, set viewport, then capture. [BrowserCat Playwright cheatsheet]
Or skip the browser setup
ScreenshotNeo can return an image from one API request. Its API supports viewport settings and other capture options; see the ScreenshotNeo API documentation for parameter names and setup.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Visit ScreenshotNeo or sign up free.
FAQ
Does changing the viewport make the screenshot full-page?
No. Use fullPage: true when the whole document should be captured.
Are 2000 × 1000 the maximum BrowserCat viewport dimensions?
No limit is stated in the cited documentation; those dimensions are an example.
Should viewport size be set before or after navigation?
Set it before taking the screenshot. The documented operation is to resize the viewport before screenshot capture. Setting it before navigation can also make the page load at the intended layout width.
