What Is Playwright’s Default Viewport Size?

Playwright’s default viewport size is 1280 × 720 pixels. This fixed, emulated page viewport is the documented default for a normal BrowserContext and for Playwright Test’s testOptions.viewport.

The viewport describes the page’s layout area. It is separate from the host computer’s physical display, the screen dimensions exposed to the page, and the device scale factor used for rendering.

What is Playwright’s default viewport size?

Unless you configure another value, Playwright creates pages at:

Setting	Default	What it controls
`viewport`	`{ width: 1280, height: 720 }`	The emulated CSS viewport used for page layout
`deviceScaleFactor`	`1`	The ratio between CSS pixels and device pixels
`screen`	Separate setting	The screen dimensions reported to the page

Playwright’s BrowserContext API documents the viewport default as “an 1280×720 viewport.” The same dimensions are used by Playwright Test unless a project, device preset, or test overrides them.

See the BrowserContext viewport option, Playwright Test viewport option, and official emulation guide.

BrowserContext: use the documented default explicitly

You normally do not need to specify the default. Setting it explicitly can make a shared configuration easier to understand and prevents an accidental change elsewhere.

import { chromium } from 'playwright';

const browser = await chromium.launch();
const context = await browser.newContext({
  viewport: { width: 1280, height: 720 },
});

const page = await context.newPage();
await page.goto('https://example.com');
console.log(await page.evaluate(() => ({
  innerWidth: window.innerWidth,
  innerHeight: window.innerHeight,
})));

await browser.close();

The page will report a layout viewport of 1280 by 720 CSS pixels. Headless mode does not change this default.

Playwright Test: configure the viewport

Set the viewport in playwright.config.ts when every test in a project should use the same dimensions.

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    viewport: { width: 1280, height: 720 },
  },
});

A complete test can inspect the dimensions before making assertions:

import { test, expect } from '@playwright/test';

test('uses the configured viewport', async ({ page }) => {
  await page.goto('https://example.com');
  expect(await page.evaluate(() => window.innerWidth)).toBe(1280);
  expect(await page.evaluate(() => window.innerHeight)).toBe(720);
});

How to change the Playwright viewport size

Set a custom BrowserContext viewport

const context = await browser.newContext({
  viewport: { width: 1440, height: 900 },
});

Viewport dimensions are numbers in CSS pixels. Use the dimensions your application is designed to support, and keep them stable across local and CI runs.

Set a project-wide Test viewport

import { defineConfig } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'desktop',
      use: {
        viewport: { width: 1440, height: 900 },
      },
    },
    {
      name: 'compact-desktop',
      use: {
        viewport: { width: 1024, height: 768 },
      },
    },
  ],
});

Change the size with `page.setViewportSize()`

await page.setViewportSize({ width: 1024, height: 768 });
await page.goto('https://example.com');

Set the size before navigation when the site changes its markup or behavior based on the initial viewport. If you resize after navigation, responsive code may already have run at the previous dimensions.

What does `viewport: null` mean?

viewport: null disables Playwright’s consistent viewport emulation. The page then uses the host browser window size. That can be useful when you specifically need a real window, but the dimensions can differ between a developer laptop, a CI worker, headed mode, and headless mode.

const context = await browser.newContext({
  viewport: null,
});

Because the host window controls the result, null can make screenshots and layout assertions nondeterministic. Prefer an explicit width and height for visual regression tests, generated screenshots, and reproducible CI runs.

Device presets and viewport overrides

Device descriptors can provide a viewport, user agent, touch support, and other emulation settings. If you spread a device preset and then specify viewport, your explicit value wins.

import { chromium, devices } from 'playwright';

const browser = await chromium.launch();
const context = await browser.newContext({
  ...devices['Desktop Chrome'],
  viewport: { width: 1280, height: 720 },
});

The order matters. This uses 1280 × 720:

use: {
  ...devices['Desktop Chrome'],
  viewport: { width: 1280, height: 720 },
}

This lets the device preset’s viewport replace your earlier value:

use: {
  viewport: { width: 1280, height: 720 },
  ...devices['Desktop Chrome'],
}

For mobile emulation, use the device preset’s intended viewport unless you have a specific reason to override it. A custom viewport can describe a size that does not match the selected device’s other characteristics.

Viewport, screen, and device scale factor are different

These settings are related but not interchangeable:

Viewport: the CSS layout area used by the page.
Screen: the screen dimensions reported to web APIs when configured.
Device scale factor: the rendering scale between CSS pixels and device pixels.

const context = await browser.newContext({
  viewport: { width: 1280, height: 720 },
  screen: { width: 1920, height: 1080 },
  deviceScaleFactor: 2,
});

A 1280 × 720 viewport with a scale factor of 2 still has a 1280 × 720 CSS layout. The rendered bitmap can contain more physical pixels.

Full-page screenshots and viewport height

The default height, 720 pixels, is the initially visible area. A full-page screenshot can extend below it to include the document’s scrollable content.

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

Use an explicit viewport width when comparing full-page screenshots. A width change can alter line wrapping, lazy-loaded content, breakpoint behavior, and the final document height.

Common errors and fixes

Symptom	Cause	Fix
The page is not 1280 × 720	A project, fixture, device preset, or test overrides the default	Search configuration for `viewport`; log `window.innerWidth` and `window.innerHeight`
Dimensions change in CI	`viewport: null` delegates sizing to the host window	Use an explicit viewport for deterministic runs
My device preset ignores the custom size	The preset is spread after the custom `viewport`	Spread the preset first, then set `viewport`
Responsive behavior looks wrong after resize	The page loaded at a different size before `setViewportSize()`	Set the viewport in the context or before navigation
Screenshot pixel dimensions seem larger than 1280 × 720	A device scale factor or screenshot scale changes physical pixels	Check `deviceScaleFactor` and screenshot options separately from CSS dimensions
Assertions pass locally but fail in another project	Projects may use different viewport or device settings	Declare viewport per project and report it in failure diagnostics

Performance and reliability guidance

Use a fixed viewport to reduce layout variance and make visual snapshots comparable.
Reuse a browser process, while creating isolated contexts for tests that need separate cookies and storage.
Choose the smallest viewport that covers the behavior under test; very large pages can require more layout and screenshot work.
For responsive coverage, define a small set of intentional viewport projects instead of relying on the machine window size.
When debugging a mismatch, record viewport width, height, device scale factor, browser, and whether a device preset was applied.

Or skip the browser setup

If your goal is a reliable website screenshot rather than browser automation, ScreenshotNeo provides a single screenshot API request. Its options include custom viewports, device presets, full-page capture, retina scale, element capture, waits, custom CSS and JavaScript, and PDF output. The API also accepts parameter names used by other screenshot services, which can simplify migration.

See the ScreenshotNeo documentation for the complete request options.

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

import 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}`);

Cookie and consent banners are accepted and removed before capture, along with more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and whether the request was billed. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account and use the API or MCP server when you do not need to maintain browser setup.

FAQ

Is Playwright’s default viewport 1280 × 720?

Yes. That is the documented default for BrowserContext and Playwright Test when no override or device preset changes it.

Does 1280 × 720 describe my monitor?

No. It describes the emulated page viewport. Your monitor and browser window can have different physical dimensions.

Should I use `viewport: null` for headed tests?

Only when host-window sizing is part of what you need to test. Use an explicit viewport when reproducibility matters.

Can I set only the viewport width?

No. Playwright’s viewport setting takes both width and height. Provide both values.

Does device scale factor change CSS breakpoints?

No. CSS breakpoints respond to the CSS viewport. Device scale factor changes rendering density and physical pixels.