​
Overview

A viewport defines the visible area of a web page in a browser window. While setting a custom viewport is optional in Browserbase, it can be helpful for specific use cases — such as visual testing, screenshot generation, or automations that rely on precise layout behavior. By default, Browserbase generates realistic, randomized viewports to enhance stealth and reduce detection. However, if your automation requires a consistent viewport size (e.g., for comparing screenshots across sessions), you can select from a predefined set of supported dimensions.

​
Supported Viewport Sizes

When creating a session, you can choose from the following approved viewport dimensions. These values are optimized for reliability and stealth, and are the only sizes currently supported.

​
Desktop Viewports

WidthHeightDevice
19201080Standard Full HD (Desktop)
1366768Widescreen Laptop
1536864High-Resolution Laptop
1280720Small Desktop Monitor
1024768Minimum Supported Desktop Viewport

​
Mobile Viewports

WidthHeightDevice
414896iPhone XR, iPhone 11
390844iPhone 12, iPhone 13, iPhone 14
375812iPhone X, iPhone XS
360800Standard Android Phone
320568iPhone SE, Small Devices
Only the viewports listed above are supported. Custom dimensions outside these values are not allowed to ensure consistent performance, rendering accuracy, and anti-bot stealth effectiveness.

​
How to Set a Viewport in Your Session

Use the viewport and fingerprint.screen fields when creating a session to specify the desired width and height. Below are examples in both Node.js and Python SDKs. 
import Browserbase from "@browserbasehq/sdk";

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

async function createBasicStealthSession() {
  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
    browserSettings: {
      fingerprint: {
        screen: {
          maxWidth: 1920,
          maxHeight: 1080,
          minWidth: 1024,
          minHeight: 768,
        }
      },
      viewport: {
        width: 1920,
        height: 1080,
      },
    },
  });
  console.log(`Session URL: https://browserbase.com/sessions/${session.id}`);
  return session;
}

const session = createBasicStealthSession();
Custom viewports are a powerful feature when precision matters — whether you’re automating mobile interactions, capturing consistent screenshots, or testing responsive layouts. For most use cases, Browserbase’s default viewport generation provides the best balance of stealth and reliability. Only configure a specific viewport if your use case requires it. For a full list of session options and configuration fields, check out the API reference for creating a session.