From 34a37857af5e009127dd39dc21ac6ba82ce1ba37 Mon Sep 17 00:00:00 2001 From: Jay Kothari Date: Wed, 5 Aug 2026 11:45:41 -0700 Subject: [PATCH] docs: clarify viewport sets window size, not page viewport Customer feedback: a 1280x800 viewport appeared "cut off" because on headful browsers the Chromium UI (tab strip, toolbar) consumes part of the window height, so the visible page area is shorter than the configured height. Add a section explaining window size vs. page viewport with workarounds (set the page viewport via the automation framework, or pad the height), and correct the screenshots bullet in Considerations. Co-Authored-By: Claude Fable 5 --- browsers/viewport.mdx | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/browsers/viewport.mdx b/browsers/viewport.mdx index 638fe69..9d49143 100644 --- a/browsers/viewport.mdx +++ b/browsers/viewport.mdx @@ -135,6 +135,32 @@ func main() { The `refresh_rate` parameter only applies to live view sessions and is ignored for [headless](/browsers/headless) browsers. +## Window size vs. page viewport + +The `viewport` parameter sets the dimensions of the browser **window**, not the visible page area. On headful browsers, Chromium's UI (tab strip and toolbar) occupies part of the window height, so the page renders in a slightly shorter area than the configured height. For example, with a 1280x800 viewport, `window.innerHeight` will be less than 800 and content near the bottom of the page may not be visible in screenshots or live view. + +If your automation expects an exact page viewport, either: + +- **Set the page viewport through your automation framework**, which controls the rendered page size directly regardless of the window dimensions: + + + +```typescript Typescript/Javascript +// Playwright +await page.setViewportSize({ width: 1280, height: 800 }); +``` + +```python Python +# Playwright +await page.set_viewport_size({"width": 1280, "height": 800}) +``` + + + +- **Account for the browser UI when choosing dimensions** by adding its height to the `height` you pass to Kernel, so the remaining page area matches your target size. + +On [headless](/browsers/headless) browsers there is no browser UI, so the page viewport matches the configured dimensions exactly. + ## Supported viewport configurations Kernel supports specific viewport configurations tuned for optimal performance and Computer Use compatibility. When you provide width and height without specifying refresh_rate, it will be automatically determined if the dimensions match one of the supported resolutions exactly. The following resolutions are supported: @@ -414,4 +440,4 @@ if err != nil { - The viewport configuration is set when the browser is created and applies to the initial browser window - Higher resolutions (like 2560x1440) may impact the performance and responsiveness of live view sessions - The viewport size affects how websites render, especially those with responsive designs -- Screenshots taken from the browser will match the configured viewport dimensions +- Screenshots taken through your automation framework capture the page viewport, which on headful browsers is shorter than the configured dimensions due to the browser UI (see [Window size vs. page viewport](#window-size-vs-page-viewport))