Viewports

Configure viewport sizes for your sessions

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.

Configuring the Viewport

Use the viewport field when creating a session to specify the desired width and height. Below are examples in both Node.js and Python SDKs.

Node.js

SDK

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: {
      viewport: {
        width: 1920,
        height: 1080
      }
    },
  });
  console.log(`Session URL: https://browserbase.com/sessions/${session.id}`);
  return session;
}

const session = createBasicStealthSession();

Python

SDK

from browserbase import Browserbase
import os

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

def createBasicStealthSession():
    session = bb.sessions.create(
        project_id=os.environ["BROWSERBASE_PROJECT_ID"],
        browser_settings={
            "viewport": {
              "width": 1920, 
              "height": 1080
              },
        },
    )
    print(f"Session URL: https://browserbase.com/sessions/{session.id}")
    return session

session = createBasicStealthSession()

Browser sessions with basic stealth allow for any custom viewport dimensions. Browser sessions with advanced stealth require a viewport configuration that matches the os you specify; see our advanced stealth customization guide for more details.

Setting the Viewport with Puppeteer

If you are using Puppeteer as your browser automation framework, Puppeteer applies an 800 x 600 default viewport by default. To customize these dimensions, you will also need to set the defaultViewport to null as shown below.

Node.js

const session = await bb.sessions.create({
  projectId: BROWSERBASE_PROJECT_ID,
  browserSettings: {
    viewport: {
      width: 1920,
      height: 1080
    }
  },
});

const browser = await puppeteer.connect({
  browserWSEndpoint: session.connectUrl,
  defaultViewport: null // Prevents 800x600 default viewport
});

For a full list of session options and configuration fields, check out the API reference for creating a session.