> ## Documentation Index
> Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-docs-website-deploy-hook.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Viewports

> Configure browser viewport size and refresh rate for your automations

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. The refresh rate can be explicitly specified or automatically determined based on the width and height if they match a supported configuration.

## Default viewport

If the `viewport` parameter is omitted when creating a browser, the default configuration is 1920x1080 at 25Hz.

<CodeGroup>
  ```typescript Typescript/Javascript theme={null}
  // Uses default viewport (1920x1080@25Hz)
  const defaultViewport = await kernel.browsers.create();
  ```

  ```python Python theme={null}
  # Uses default viewport (1920x1080@25Hz)
  default_viewport = kernel.browsers.create()
  ```

  ```go Go theme={null}
  // Uses default viewport (1920x1080@25Hz)
  defaultViewport, err := client.Browsers.New(ctx, kernel.BrowserNewParams{})
  if err != nil {
  	panic(err)
  }
  _ = defaultViewport
  ```
</CodeGroup>

## Setting viewport configuration

You can configure the viewport when creating a browser by specifying the `viewport` parameter with `width` and `height`. The `refresh_rate` is optional and will be automatically determined from the dimensions if they match a supported configuration:

<Info>
  Setting a custom viewport configuration triggers a Chromium restart, which can take several seconds. Use [browser pools](/browsers/pools/overview) to access browsers with custom viewport configurations faster.
</Info>

<CodeGroup>
  ```typescript Typescript/Javascript theme={null}
  import Kernel from '@onkernel/sdk';

  const kernel = new Kernel();

  // Explicitly specify refresh rate
  const kernelBrowser = await kernel.browsers.create({
    viewport: {
      width: 1920,
      height: 1080,
      refresh_rate: 25
    }
  });

  // Auto-determine refresh rate from dimensions (25Hz for 1920x1080)
  const kernelBrowserAuto = await kernel.browsers.create({
    viewport: {
      width: 1920,
      height: 1080
    }
  });
  ```

  ```python Python theme={null}
  from kernel import Kernel

  kernel = Kernel()

  # Explicitly specify refresh rate
  kernel_browser = kernel.browsers.create(
      viewport={
          "width": 1920,
          "height": 1080,
          "refresh_rate": 25
      }
  )

  # Auto-determine refresh rate from dimensions (25Hz for 1920x1080)
  kernel_browser_auto = kernel.browsers.create(
      viewport={
          "width": 1920,
          "height": 1080
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"

  	"github.com/kernel/kernel-go-sdk"
  	"github.com/kernel/kernel-go-sdk/shared"
  )

  func main() {
  	ctx := context.Background()
  	client := kernel.NewClient()

  	// Explicitly specify refresh rate
  	kernelBrowser, err := client.Browsers.New(ctx, kernel.BrowserNewParams{
  		Viewport: shared.BrowserViewportParam{
  			Width:       1920,
  			Height:      1080,
  			RefreshRate: kernel.Int(25),
  		},
  	})
  	if err != nil {
  		panic(err)
  	}
  	_ = kernelBrowser

  	// Auto-determine refresh rate from dimensions (25Hz for 1920x1080)
  	kernelBrowserAuto, err := client.Browsers.New(ctx, kernel.BrowserNewParams{
  		Viewport: shared.BrowserViewportParam{
  			Width:  1920,
  			Height: 1080,
  		},
  	})
  	if err != nil {
  		panic(err)
  	}
  	_ = kernelBrowserAuto
  }
  ```
</CodeGroup>

<Info>
  The `refresh_rate` parameter only applies to live view sessions and is ignored for [headless](/browsers/headless) browsers.
</Info>

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

| Resolution | Width | Height | Refresh Rate |
| ---------- | ----- | ------ | ------------ |
| QHD        | 2560  | 1440   | 10 Hz        |
| Full HD    | 1920  | 1080   | 25 Hz        |
| WUXGA      | 1920  | 1200   | 25 Hz        |
| WXGA+      | 1440  | 900    | 25 Hz        |
| WXGA       | 1280  | 800    | 60 Hz        |
| WXGA       | 1200  | 800    | 60 Hz        |
| XGA        | 1024  | 768    | 60 Hz        |
| Tablet     | 768   | 1024   | 60 Hz        |
| Mobile     | 390   | 844    | 60 Hz        |

When specifying a viewport:

* **Width** and **Height** are required
* **Viewport configurations** outside of the supported list are available, but they are provided on a "use at your own risk" basis and may not work as expected.
* **Refresh Rate** is optional - if omitted, it will be automatically determined from the width and height combination

## Example configurations

<CodeGroup>
  ```typescript Typescript/Javascript theme={null}
  // Full HD (1920x1080) at 25Hz - explicit refresh rate
  const fullHD = await kernel.browsers.create({
    viewport: {
      width: 1920,
      height: 1080,
      refresh_rate: 25
    }
  });

  // Full HD (1920x1080) - auto-determined 25Hz (Default configuration)
  const fullHDAuto = await kernel.browsers.create({
    viewport: {
      width: 1920,
      height: 1080
    }
  });

  // QHD (2560x1440) - auto-determined 10Hz
  // Note: May affect live view responsiveness
  const qhd = await kernel.browsers.create({
    viewport: {
      width: 2560,
      height: 1440
    }
  });

  // XGA (1024x768) - auto-determined 60Hz
  const xga = await kernel.browsers.create({
    viewport: {
      width: 1024,
      height: 768
    }
  });

  // WUXGA (1920x1200) at 25Hz - explicit refresh rate
  const wuxga = await kernel.browsers.create({
    viewport: {
      width: 1920,
      height: 1200,
      refresh_rate: 25
    }
  });
  ```

  ```python Python theme={null}
  # Full HD (1920x1080) at 25Hz - explicit refresh rate
  full_hd = kernel.browsers.create(
      viewport={
          "width": 1920,
          "height": 1080,
          "refresh_rate": 25
      }
  )

  # Full HD (1920x1080) - auto-determined 25Hz (Default configuration)
  full_hd_auto = kernel.browsers.create(
      viewport={
          "width": 1920,
          "height": 1080
      }
  )

  # QHD (2560x1440) - auto-determined 10Hz
  # Note: May affect live view responsiveness
  qhd = kernel.browsers.create(
      viewport={
          "width": 2560,
          "height": 1440
      }
  )

  # XGA (1024x768) - auto-determined 60Hz
  xga = kernel.browsers.create(
      viewport={
          "width": 1024,
          "height": 768
      }
  )

  # WUXGA (1920x1200) at 25Hz - explicit refresh rate
  wuxga = kernel.browsers.create(
      viewport={
          "width": 1920,
          "height": 1200,
          "refresh_rate": 25
      }
  )
  ```

  ```go Go theme={null}
  // Full HD (1920x1080) at 25Hz - explicit refresh rate
  fullHD, err := client.Browsers.New(ctx, kernel.BrowserNewParams{
  	Viewport: shared.BrowserViewportParam{
  		Width:       1920,
  		Height:      1080,
  		RefreshRate: kernel.Int(25),
  	},
  })
  if err != nil {
  	panic(err)
  }
  _ = fullHD

  // Full HD (1920x1080) - auto-determined 25Hz (Default configuration)
  fullHDAuto, err := client.Browsers.New(ctx, kernel.BrowserNewParams{
  	Viewport: shared.BrowserViewportParam{
  		Width:  1920,
  		Height: 1080,
  	},
  })
  if err != nil {
  	panic(err)
  }
  _ = fullHDAuto

  // QHD (2560x1440) - auto-determined 10Hz
  // Note: May affect live view responsiveness
  qhd, err := client.Browsers.New(ctx, kernel.BrowserNewParams{
  	Viewport: shared.BrowserViewportParam{
  		Width:  2560,
  		Height: 1440,
  	},
  })
  if err != nil {
  	panic(err)
  }
  _ = qhd

  // XGA (1024x768) - auto-determined 60Hz
  xga, err := client.Browsers.New(ctx, kernel.BrowserNewParams{
  	Viewport: shared.BrowserViewportParam{
  		Width:  1024,
  		Height: 768,
  	},
  })
  if err != nil {
  	panic(err)
  }
  _ = xga

  // WUXGA (1920x1200) at 25Hz - explicit refresh rate
  wuxga, err := client.Browsers.New(ctx, kernel.BrowserNewParams{
  	Viewport: shared.BrowserViewportParam{
  		Width:       1920,
  		Height:      1200,
  		RefreshRate: kernel.Int(25),
  	},
  })
  if err != nil {
  	panic(err)
  }
  _ = wuxga
  ```
</CodeGroup>

## Dynamically changing the viewport

You can change the viewport of a browser after it has been created using the [update browser endpoint](https://kernel.sh/docs/api-reference/browsers/update-browser-session).

<CodeGroup>
  ```typescript Typescript/Javascript theme={null}
  // Create a browser with default viewport
  const kernelBrowser = await kernel.browsers.create();

  // Later, change the viewport
  await kernel.browsers.update(kernelBrowser.session_id, {
    viewport: {
      width: 1024,
      height: 768
    }
  });
  ```

  ```python Python theme={null}
  # Create a browser with default viewport
  kernel_browser = await kernel.browsers.create()

  # Later, change the viewport
  await kernel.browsers.update(kernel_browser.session_id, viewport={"width": 1024, "height": 768})
  ```

  ```go Go theme={null}
  // Create a browser with default viewport
  kernelBrowser, err := client.Browsers.New(ctx, kernel.BrowserNewParams{})
  if err != nil {
  	panic(err)
  }

  // Later, change the viewport
  _, err = client.Browsers.Update(ctx, kernelBrowser.SessionID, kernel.BrowserUpdateParams{
  	Viewport: kernel.BrowserUpdateParamsViewport{
  		BrowserViewportParam: shared.BrowserViewportParam{
  			Width:  1024,
  			Height: 768,
  		},
  	},
  })
  if err != nil {
  	panic(err)
  }
  ```
</CodeGroup>

<Warning>
  There are important limitations when changing the viewport:

  * **Headful browsers**: You can't resize the viewport while [live view](/browsers/live-view) is active or while a [replay](/browsers/replays) is actively recording unless you set the `force` flag to `true`.
  * **Headless browsers**: Changing the viewport triggers a Chromium restart, which takes several seconds and may disrupt active CDP connections.
</Warning>

### Force resizing during recording

If you need to resize the viewport while a replay is actively recording, set `force` to `true` in the update request. This stops the current recording, resizes the viewport, and restarts the recording — resulting in multiple replay segments for the session.

<CodeGroup>
  ```typescript Typescript/Javascript theme={null}
  await kernel.browsers.update(kernelBrowser.session_id, {
    viewport: {
      width: 1024,
      height: 768,
      force: true
    }
  });
  ```

  ```python Python theme={null}
  await kernel.browsers.update(
      kernel_browser.session_id,
      viewport={"width": 1024, "height": 768, "force": True}
  )
  ```

  ```go Go theme={null}
  _, err := client.Browsers.Update(ctx, kernelBrowser.SessionID, kernel.BrowserUpdateParams{
  	Viewport: kernel.BrowserUpdateParamsViewport{
  		BrowserViewportParam: shared.BrowserViewportParam{
  			Width:  1024,
  			Height: 768,
  		},
  		Force: kernel.Bool(true),
  	},
  })
  if err != nil {
  	panic(err)
  }
  ```
</CodeGroup>

## Considerations

* 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