Skip to content

Commit d719d69

Browse files
hiroTamadahiroTamada
committed
Configurable viewport docs
1 parent 0c3622c commit d719d69

File tree

2 files changed

+170
-0
lines changed

2 files changed

+170
-0
lines changed

‎browsers/viewport.mdx‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
title: "Viewport Configuration"
3+
description: "Configure browser viewport size and refresh rate for your automations"
4+
---
5+
6+
Kernel browsers allow you to configure the viewport size and refresh rate when creating a browser session. The viewport configuration determines the initial browser window dimensions and display refresh rate.
7+
8+
## Setting viewport configuration
9+
10+
You can configure the viewport when creating a browser by specifying the `viewport` parameter with `width`, `height`, and `refresh_rate`:
11+
12+
<CodeGroup>
13+
14+
```typescript Typescript/Javascript
15+
const kernelBrowser = await kernel.browsers.create({
16+
viewport: {
17+
width: 1920,
18+
height: 1080,
19+
refresh_rate: 25
20+
}
21+
});
22+
```
23+
24+
```python Python
25+
kernel_browser = client.browsers.create(
26+
viewport={
27+
"width": 1920,
28+
"height": 1080,
29+
"refresh_rate": 25
30+
}
31+
)
32+
```
33+
34+
</CodeGroup>
35+
36+
## Supported viewport configurations
37+
38+
Kernel supports specific viewport configurations. The server will reject unsupported combinations. The following resolutions are supported:
39+
40+
| Resolution | Width | Height | Refresh Rate |
41+
|------------|-------|--------|--------------|
42+
| QHD | 2560 | 1440 | 10 Hz |
43+
| Full HD | 1920 | 1080 | 25 Hz |
44+
| WUXGA | 1920 | 1200 | 25 Hz |
45+
| WXGA+ | 1440 | 900 | 25 Hz |
46+
| XGA | 1024 | 768 | 60 Hz |
47+
48+
<Warning>
49+
Higher resolutions may affect the responsiveness of [live view](/browsers/live-view) browser sessions.
50+
</Warning>
51+
52+
## Example configurations
53+
54+
<CodeGroup>
55+
56+
```typescript Typescript/Javascript
57+
// Full HD (1920x1080) at 25Hz
58+
const fullHD = await kernel.browsers.create({
59+
viewport: {
60+
width: 1920,
61+
height: 1080,
62+
refresh_rate: 25
63+
}
64+
});
65+
66+
// QHD (2560x1440) at 10Hz - Note: May affect live view responsiveness
67+
const qhd = await kernel.browsers.create({
68+
viewport: {
69+
width: 2560,
70+
height: 1440,
71+
refresh_rate: 10
72+
}
73+
});
74+
75+
// XGA (1024x768) at 60Hz - Default configuration
76+
const xga = await kernel.browsers.create({
77+
viewport: {
78+
width: 1024,
79+
height: 768,
80+
refresh_rate: 60
81+
}
82+
});
83+
84+
// WUXGA (1920x1200) at 25Hz
85+
const wuxga = await kernel.browsers.create({
86+
viewport: {
87+
width: 1920,
88+
height: 1200,
89+
refresh_rate: 25
90+
}
91+
});
92+
```
93+
94+
```python Python
95+
# Full HD (1920x1080) at 25Hz
96+
full_hd = await client.browsers.create(
97+
viewport={
98+
"width": 1920,
99+
"height": 1080,
100+
"refresh_rate": 25
101+
}
102+
)
103+
104+
# QHD (2560x1440) at 10Hz - Note: May affect live view responsiveness
105+
qhd = await client.browsers.create(
106+
viewport={
107+
"width": 2560,
108+
"height": 1440,
109+
"refresh_rate": 10
110+
}
111+
)
112+
113+
# XGA (1024x768) at 60Hz - Default configuration
114+
xga = await client.browsers.create(
115+
viewport={
116+
"width": 1024,
117+
"height": 768,
118+
"refresh_rate": 60
119+
}
120+
)
121+
122+
# WUXGA (1920x1200) at 25Hz
123+
wuxga = await client.browsers.create(
124+
viewport={
125+
"width": 1920,
126+
"height": 1200,
127+
"refresh_rate": 25
128+
}
129+
)
130+
```
131+
132+
</CodeGroup>
133+
134+
## Default viewport
135+
136+
If the `viewport` parameter is omitted when creating a browser, the default configuration is typically 1024x768 at 60Hz.
137+
138+
<CodeGroup>
139+
140+
```typescript Typescript/Javascript
141+
// Uses default viewport (1024x768@60Hz)
142+
const defaultViewport = await kernel.browsers.create();
143+
```
144+
145+
```python Python
146+
# Uses default viewport (1024x768@60Hz)
147+
default_viewport = await client.browsers.create()
148+
```
149+
150+
</CodeGroup>
151+
152+
## Viewport constraints
153+
154+
The viewport configuration has the following constraints:
155+
- **Width**: Minimum 320px, Maximum 7680px
156+
- **Height**: Minimum 240px, Maximum 4320px
157+
- **Refresh Rate**: Must match the supported configurations listed above
158+
159+
<Note>
160+
While the API accepts width and height values within the min/max ranges, only the specific resolution and refresh rate combinations listed in the supported configurations table are actually supported. The server will reject any unsupported combinations.
161+
</Note>
162+
163+
## Considerations
164+
165+
- The viewport configuration is set when the browser is created and applies to the initial browser window
166+
- Higher resolutions (like 2560x1440) may impact the performance and responsiveness of live view sessions
167+
- The viewport size affects how websites render, especially those with responsive designs
168+
- Screenshots taken from the browser will match the configured viewport dimensions
169+
- In [headless mode](/browsers/headless), the viewport configuration still applies for rendering and screenshots

‎docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@
5757
"pages": [
5858
"browsers/create-a-browser",
5959
"browsers/headless",
60+
"browsers/viewport",
6061
"browsers/standby",
6162
"browsers/persistence",
6263
"browsers/profiles",

0 commit comments

Comments
 (0)