Skip to content

docs: clarify viewport sets window size, not page viewport #482

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Jayko001 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: clarify viewport sets window size, not page viewport #482

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 27 additions & 1 deletion browsers/viewport.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,32 @@ func main() {
The `refresh_rate` parameter only applies to live view sessions and is ignored for [headless](/browsers/headless) browsers.
</Info>

## 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:

<CodeGroup>

```typescript Typescript/Javascript
// Playwright
await page.setViewportSize({ width: 1280, height: 800 });
```

```python Python
# Playwright
await page.set_viewport_size({"width": 1280, "height": 800})
```

</CodeGroup>

- **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:
Expand Down Expand Up @@ -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))
Loading