Viewport parameters

Control the size and device characteristics Chrome uses to render your image.

How it works

The viewport is the visible area of the browser page. By default, Chrome renders pages in a 1920x1080 viewport. Use the viewport parameters to render responsive layouts at a specific size or emulate mobile, landscape, and touch behavior.

Parameters

The three Boolean parameters are optional and default to false. They can be used together, but they do not set the viewport dimensions. Use viewport_width and viewport_height to choose the exact layout size.

Setting viewport width and height

Both dimensions must be included when setting the viewport:

curl -X POST https://hcti.io/v1/image -u 'UserID:APIKey' \
     --data-urlencode url="https://example.com" \
     --data viewport_width=1200 \
     --data viewport_height=630

{
  "url": "https://example.com",
  "viewport_width": 1200,
  "viewport_height": 630
}

Setting explicit dimensions disables automatic cropping and returns the area rendered inside the viewport. For HTML snippets that should be tightly cropped to their content, set the dimensions in CSS instead.

Emulating a mobile viewport

Combine a mobile-sized viewport with mobile emulation:

{
  "url": "https://example.com",
  "viewport_width": 390,
  "viewport_height": 844,
  "viewport_mobile": true
}

viewport_mobile enables Chrome’s mobile viewport behavior, including support for a page’s <meta name="viewport"> settings.

Using landscape orientation

viewport_landscape works independently of viewport_mobile. It can be used with mobile, tablet, or desktop-sized viewports.

For example, render a tablet-sized viewport in landscape orientation with touch support:

{
  "url": "https://example.com",
  "viewport_width": 1180,
  "viewport_height": 820,
  "viewport_landscape": true,
  "viewport_touch": true
}

Add viewport_mobile: true only when you also want Chrome’s mobile viewport behavior.

Enabling touch support

Set viewport_touch to true to enable touch-capability detection for pages that adapt their controls or interactions for touch devices:

{
  "url": "https://example.com",
  "viewport_width": 390,
  "viewport_height": 844,
  "viewport_mobile": true,
  "viewport_touch": true
}

Interactions with other parameters

The viewport is Chrome’s virtual screen, measured in CSS pixels. It controls the page layout but does not necessarily determine the final image dimensions.

• device_scale changes the output resolution without changing the CSS viewport size. A 1000x1000 viewport with device_scale: 1.5 produces a 1500x1500 image.
• full_screen can produce an image taller than viewport_height by capturing content below the initial viewport.
• selector crops the final image to a specific element rendered inside the configured viewport.
• Automatic cropping controls the bounds of the final image after the page has been rendered.
• The width and height query parameters can resize the generated image on the fly without changing the viewport or rerendering the page.

Need help?

We’re always looking to improve this documentation. Please send us an email: support@htmlcsstoimage.com. We respond fast.