Implementation:Puppeteer Puppeteer Page Emulate

Knowledge Sources	Puppeteer Puppeteer API
Domains	Browser_Automation, Responsive_Design
Last Updated	2026-02-11 23:00 GMT

Overview

Concrete tool for emulating a specific device's viewport and user agent on a Puppeteer Page.

Description

The Page.emulate() method configures a page to simulate a target device. It is a convenience method that combines page.setUserAgent() and page.setViewport() into a single call. The method accepts a Device descriptor object, which can be obtained from the built-in KnownDevices catalog containing definitions for popular mobile devices.

The device catalog is defined in packages/puppeteer-core/src/common/Device.ts and includes over 80 device profiles.

Usage

Call this method before navigating to a URL to ensure the page renders with the correct viewport dimensions and user agent from the start.

Code Reference

Source Location

• Repository: puppeteer
• File: packages/puppeteer-core/src/api/Page.ts
• Lines: 2079-2084

Signature

class Page {
  async emulate(device: Device): Promise<void> {
    await Promise.all([
      this.setUserAgent({userAgent: device.userAgent}),
      this.setViewport(device.viewport),
    ]);
  }
}

Import

import puppeteer, {KnownDevices} from 'puppeteer';
// Access devices via KnownDevices or puppeteer.devices
const iPhone = KnownDevices['iPhone 6'];

I/O Contract

Inputs

Name	Type	Required	Description
device	Device	Yes	Device descriptor with userAgent and viewport properties
device.userAgent	string	Yes	User agent string to emulate
device.viewport	Viewport	Yes	Viewport configuration (width, height, deviceScaleFactor, isMobile, hasTouch, isLandscape)

Outputs

Name	Type	Description
return	Promise<void>	Resolves when both user agent and viewport have been set

Usage Examples

Emulate iPhone 6

const puppeteer = require('puppeteer');

const browser = await puppeteer.launch();
const page = await browser.newPage();

// Emulate iPhone 6 before navigation
await page.emulate(puppeteer.devices['iPhone 6']);
await page.goto('https://www.nytimes.com/');
await page.screenshot({path: 'mobile-view.png', fullPage: true});
await browser.close();

Custom Device Descriptor

const customDevice = {
  userAgent: 'Mozilla/5.0 (Custom Device) AppleWebKit/537.36',
  viewport: {
    width: 390,
    height: 844,
    deviceScaleFactor: 3,
    isMobile: true,
    hasTouch: true,
    isLandscape: false,
  },
};
await page.emulate(customDevice);

Related Pages

Implements Principle

• Principle:Puppeteer_Puppeteer_Device_Emulation

Requires Environment

• Environment:Puppeteer_Puppeteer_Node_18_Runtime