To emulate a named phone or tablet in Puppeteer, create a page, call page.emulate(KnownDevices['device name']), then navigate. For a custom layout, call page.setViewport() before navigation. These page-level settings emulate viewport and device metrics, and a named device profile also supplies a user agent; they are not a guarantee of complete physical-device behavior.
Emulate a named device
Puppeteer provides KnownDevices, a read-only catalog of named device profiles. Each Device has a userAgent string and viewport settings. Pass a profile to page.emulate() to apply both.
import puppeteer, {KnownDevices} from 'puppeteer';
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
const device = KnownDevices['iPhone 17 Pro'];
if (!device) {
throw new Error('Device profile not found in this Puppeteer version');
}
await page.emulate(device); // Configure before navigation.
await page.goto('https://example.com', {waitUntil: 'networkidle2'});
await page.screenshot({path: 'iphone.png', fullPage: true});
} finally {
await browser.close();
}The named iPhone 17 Pro profile appears in the current KnownDevices reference. Device keys can vary with the installed Puppeteer release, so check the documentation matching your version if a profile is missing. Page.emulate() is documented as a shortcut for setting the page’s user agent and viewport.
Use a custom viewport or device profile
Set only the viewport
If you need a particular page size but do not need a paired device user agent, set the viewport directly. The values below define a 640-by-480 CSS-pixel viewport at device scale factor 1.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problems#1 Best Overall
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.setViewport({
width: 640,
height: 480,
deviceScaleFactor: 1,
});
await page.goto('https://example.com');
await page.screenshot({path: 'custom-viewport.png'});
} finally {
await browser.close();
}Set a custom viewport and user agent together
When a custom setup needs both metrics and a specific user agent, pass a Device-shaped object to page.emulate(). Choose a user agent appropriate to your test; the example below uses a placeholder string rather than claiming to represent a particular handset.
const customDevice = {
userAgent: 'YOUR_TEST_USER_AGENT',
viewport: {
width: 390,
height: 844,
deviceScaleFactor: 3,
isMobile: true,
hasTouch: true,
},
};
await page.emulate(customDevice);
await page.goto('https://example.com');The supported shape is documented by Puppeteer’s Device interface. Use a named preset when its supplied values fit the test; use a custom object when you need explicit control.
Rank #2
Configure emulation before navigation
Set the device or viewport before calling page.goto(). Emulation resizes the page, and Puppeteer cautions that many websites do not expect a phone-sized viewport to be applied midway through a session. Also, changing isMobile or hasTouch with setViewport() can reload a page in some cases, though it does not happen on every change. See the setViewport() reference.
- Create or select the page.
- Call
page.emulate(device)for a named/custom device, orpage.setViewport(options)for viewport-only work. - Navigate only after the emulation settings are applied.
Page emulation is not browser screen configuration
page.emulate() changes one page’s device metrics and user agent. Puppeteer’s separate screen configuration controls the browser’s headless screen layout, which is useful for multi-screen scenarios rather than a substitute for mobile page emulation.
The screen configuration guide documents --screen-info, Browser.addScreen() and Browser.removeScreen() for headless use; adding or removing screens is headless-only. It states that the headless screen defaults to 800×600 when neither --screen-info nor --window-size is set. Browser.screens() is available in both headful and headless modes.
Troubleshoot common problems
- Device key is undefined: The installed Puppeteer version may not include that profile. Check the matching KnownDevices documentation, then use an available key or define a custom device object.
- The page reloads or layout changes after setup: Apply emulation before navigation. If you change
isMobileorhasTouchon an existing page, a reload is possible; account for it in the test. - The site still does not behave like a physical phone: The documented API covers user-agent and viewport/device metrics, not a guarantee of complete handset fidelity. Test the specific browser behavior your application depends on.
- A custom viewport changes layout but not server responses: A viewport-only call does not set a device user agent. Use a custom
Deviceobject with bothuserAgentandviewportif both are required.
Or skip the browser setup
For a screenshot without maintaining Puppeteer code, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns an image or PDF. Its capture flow accepts cookie/consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; each cleanup step can be turned off. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and responses identify the page verdict and billing status in headers. Its MCP server offers take_screenshot, get_page_info and capture_pdf for AI agents.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo API documentation. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for ScreenshotNeo free.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Frequently Asked Questions
Does Puppeteer device emulation guarantee that a page behaves exactly like a real phone?
No. The documented emulation covers the user agent and viewport/device metrics, not complete physical-device fidelity.
Recommended Free Tools
Can I configure a device after the page has loaded?
You can change settings, but resizing can affect the page and changing mobile or touch settings can cause a reload in some cases. Applying them before navigation is the safer sequence.
Quick Recap
Best Value
- Used Book in Good Condition
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
