Skip to main content
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. 
import Browserbase from "@browserbasehq/sdk";

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

async function createSession() {
  const session = await bb.sessions.create({
    browserSettings: {
      viewport: {
        width: 1920,
        height: 1080
      }
    },
  });
  console.log(`Session URL: https://browserbase.com/sessions/${session.id}`);
  return session;
}

const session = createSession();
Verified sessions use a fixed viewport managed by Browserbase — custom viewport dimensions are not supported with Verified. See the Verified customization guide for more details.

​
Setting the viewport with Puppeteer

If you’re using Puppeteer, it applies an 800 x 600 viewport by default. To customize these dimensions, you’ll also need to set defaultViewport to null as shown below. 
const session = await bb.sessions.create({
  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.