Viewports and device emulation

Screenshotly lets you set exact viewport dimensions and emulate device characteristics like screen density, touch support, and orientation.

Setting viewport dimensions

Use viewport_width and viewport_height to define the browser viewport size in pixels:

const screenshot = await client.capture({
  url: 'https://example.com',
  viewport_width: 1440,
  viewport_height: 900
});

Default values are 1280x1024 when not specified.

Device emulation parameters

Parameter	Type	Default	Description
`viewport_width`	integer	1280	Viewport width in pixels (100–5000)
`viewport_height`	integer	1024	Viewport height in pixels (100–5000)
`device_scale_factor`	number	1	Device pixel ratio (1–3, use 2 for retina)
`viewport_mobile`	boolean	false	Emulate mobile device behavior
`viewport_has_touch`	boolean	false	Enable touch event support
`viewport_landscape`	boolean	false	Use landscape orientation

Common device presets

Here are viewport settings for popular devices:

Device	Width	Height	Scale factor	Mobile
iPhone 14	390	844	3	true
iPhone SE	375	667	2	true
iPad Air	820	1180	2	true
iPad Mini (landscape)	1024	768	2	true
Pixel 7	412	915	2.625	true
MacBook Pro 14”	1512	982	2	false
Desktop 1080p	1920	1080	1	false

Examples

Mobile device

const screenshot = await client.capture({
  url: 'https://example.com',
  viewport_width: 390,
  viewport_height: 844,
  device_scale_factor: 3,
  viewport_mobile: true,
  viewport_has_touch: true
});

curl -X POST https://api.screenshotly.dev/v1/capture \
  -H "X-API-Key: $SCREENSHOTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "options": {
      "viewport_width": 390,
      "viewport_height": 844,
      "device_scale_factor": 3,
      "viewport_mobile": true,
      "viewport_has_touch": true
    }
  }' \
  --output screenshot.png

Tablet in landscape

const screenshot = await client.capture({
  url: 'https://example.com',
  viewport_width: 1024,
  viewport_height: 768,
  device_scale_factor: 2,
  viewport_mobile: true,
  viewport_has_touch: true,
  viewport_landscape: true
});

Retina desktop

const screenshot = await client.capture({
  url: 'https://example.com',
  viewport_width: 1440,
  viewport_height: 900,
  device_scale_factor: 2
});

Combine viewport settings with full_page: true to capture the entire page at a specific device width. The width controls how the page renders responsively, while full-page captures the complete scrollable height.

Testing responsive breakpoints

To test your site across multiple breakpoints, use batch processing with different viewport settings, or loop through common widths:

const breakpoints = [375, 768, 1024, 1440, 1920];

for (const width of breakpoints) {
  const screenshot = await client.capture({
    url: 'https://example.com',
    viewport_width: width,
    viewport_height: 800,
    full_page: true
  });
  console.log(`Captured at ${width}px`);
}

Getting started

Capture options

Advanced

Integrations

Account

Viewports and device emulation

Setting viewport dimensions

Device emulation parameters

Common device presets

Examples

Mobile device

Tablet in landscape

Retina desktop

Testing responsive breakpoints

​Setting viewport dimensions

​Device emulation parameters

​Common device presets

​Examples

​Mobile device

​Tablet in landscape

​Retina desktop

​Testing responsive breakpoints

Setting viewport dimensions

Device emulation parameters

Common device presets

Examples

Mobile device

Tablet in landscape

Retina desktop

Testing responsive breakpoints