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 use a fixed viewport managed by Browserbase — custom viewport dimensions are not supported with advanced stealth. 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.