Puppeteer does not add a decorative phone or tablet bezel to a screenshot. It can emulate a device’s viewport and user agent, then capture the page; to show that capture inside a device frame, compose the screenshot with a separate frame asset or layout afterward. The distinction matters: emulation changes how the page renders, while a frame is artwork around the rendered page.
What Puppeteer can—and cannot—put in a screenshot
Puppeteer’s screenshot API captures page content with page.screenshot(), or a particular element with elementHandle.screenshot(). The documented capture and viewport APIs do not describe a decorative hardware bezel option. So a screenshot made with Puppeteer is the page image, not a phone mockup.
Page.emulate() applies a device description’s user agent and viewport metrics. The Viewport interface also exposes properties such as width, height, device scale factor, mobile behavior, touch support and orientation. These affect the emulated browser context; they do not draw a phone outline, speaker, buttons or shadow.
The practical workflow is therefore two stages: render and capture the page at the desired device dimensions, then place that image inside a separate digital frame or custom composition. That second stage is an implementation inference from Puppeteer’s documented APIs, not a particular image-editor workflow prescribed by Puppeteer.
Choose between a known device and a custom viewport
Use a device descriptor when you want its emulation settings
Puppeteer documents Page.emulate(device) as a shortcut for applying a device’s viewport and user agent, and its documentation points to known device descriptions. This is useful when your goal is to approximate a named device’s browser behavior rather than simply render at a chosen width and height. Apply emulation before navigation where possible: Puppeteer recommends this because some sites do not expect the page to change to a phone-sized viewport after loading.
Use a custom viewport when dimensions and behavior are what matter
Set a viewport directly when you need a specific CSS-pixel width and height, or want to control options such as deviceScaleFactor, isMobile, hasTouch or isLandscape. Choose these values based on the layout you are trying to capture. A device scale factor changes the relationship between CSS pixels and output pixels; it is not a bezel setting. The Viewport API reference defines the available properties.
- Width and height: determine the emulated viewport dimensions in CSS pixels.
- Device scale factor: controls output pixel density for the emulated device; it does not add hardware details.
- Mobile and touch flags: select mobile-oriented viewport behavior and touch capability where supported by the API.
- Orientation: use the relevant landscape setting when you need a landscape viewport.
- User agent: a device descriptor can set one along with viewport metrics; do not assume that a viewport alone reproduces every behavior of a physical device.
Viewport emulation is not a guarantee that a website will behave identically to a real handset. The result is a browser-rendered page under the emulated settings. For a decorative presentation, select a frame asset or build a layout that matches the desired device appearance, output dimensions, and licensing requirements. If the composition must be repeatable in an automated build, keep the frame and positioning rules alongside the capture workflow.
Capture a page at a phone-sized viewport
The following Node.js example uses a custom viewport so its intended dimensions and flags are visible in the code. It captures the page content as a PNG. It does not create a frame; that is the next step in the workflow. The exact Puppeteer API surface can change, so check the documentation against the Puppeteer version installed in your project. The screenshot guide surfaced as version 25.12.0, while the emulation page is the current main-branch documentation.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Rank #2
- Design Your Own Canvas Prints:We Combine Your Best Memories Captured In Photographs With Our State Of The Art Technologies And Materials To Create Breathtaking And Unique Wall Decorations.
- Prints Image Resolution:Choose High-quality Photos That Feature Centered Subjects, High Resolutions, And Clear Backgrounds. Images From Your Smartphone Or Social Media Are Perfect For Small Photo Canvases, While Higher Resolution Photos Like Those From Digital Cameras Are Perfect For Larger Canvas Prints.
- Multi Frames Option Available:When You Complete Your Photo Prints Customization, You Can Choose An Additional Frame Upgrade Service. Free Installation. Multiple Colors Frames Including Gold, Silver, Black And White Wood Grain Can Be Customized. The Canvas Prints with Your Photos Will Be The Perfect Artwork With A Floating Frame.
- PROFESSIONALLY PRINTED WITH HIGH-QUALITY INKS:Highest Print Quality And Reliably Captures The Most Vibrant Colors Using Inks Which Will Last A Lifetime.A Finished Backing With Pre-installed Hanging.
- Verified by Transparency:Transparency shows you details about your product’s origins, such as its manufacturing date and location. Every item with a Transparency label includes a unique code that can be used to see details about your products.
- Install Puppeteer: in a new project, run
npm install puppeteer. Use the package version appropriate for your application and runtime. - Save the script: create
capture.mjswith the code below. - Set the target: replace the example URL with a page you are permitted to capture.
- Run it: execute
node capture.mjs. A successful run writespage.pngto the working directory. - Compose the frame: place
page.pngwithin your chosen frame asset or layout, sizing and aligning the page image to the frame’s screen opening.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({ headless: true });
try {
const page = await browser.newPage();
await page.setViewport({
width: 390,
height: 844,
deviceScaleFactor: 2,
isMobile: true,
hasTouch: true,
isLandscape: false
});
await page.goto('https://example.com', { waitUntil: 'networkidle0' });
await page.screenshot({ path: 'page.png', fullPage: false });
} finally {
await browser.close();
}The chosen dimensions are an example configuration, not a claim that they represent every phone. Change them for the viewport you want to show. Use fullPage: false for a screen-shaped viewport capture; set it to true when the complete document is needed, bearing in mind that a full-page image may not fit a frame designed for a single screen.
Capture only the page element you need
If the relevant content is a component rather than the whole page, locate it and use the element screenshot method described in Puppeteer’s screenshot guide:
const card = await page.waitForSelector('.product-card');
if (!card) throw new Error('Could not find .product-card');
await card.screenshot({ path: 'element.png' });This produces an image of the selected element, not a device frame. Element capture is useful for isolating content, but an element’s dimensions and surrounding page context may differ from a full viewport; select the capture method that matches the composition you intend to make.
Turn the capture into a device mockup
After Puppeteer writes the page image, use an image-composition step to put it behind or within a frame asset. Puppeteer’s documented capture APIs do not prescribe a compositor, asset type, or exact placement workflow, so choose one that suits your deliverable rather than treating a specific editor or library as required.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →- Choose the frame: select an appropriately licensed digital frame asset or create a simple device outline in your design system.
- Match the screen opening: note the frame’s screen rectangle and fit the screenshot to that area without distorting its aspect ratio. Crop or add background space only if the intended presentation calls for it.
- Set the final canvas: decide the total image dimensions and background independently of the browser viewport. A frame adds pixels outside the captured page.
- Keep the workflow reproducible: for automated output, store the chosen asset and layout measurements with the code, and generate the composition after each successful capture.
- Review the final image: check alignment, clipping, scaling, and whether any content extends beyond the frame’s screen opening.
For a realistic mockup, the frame’s screen cutout and the screenshot’s proportions need to agree. Increasing deviceScaleFactor can affect image resolution, but it cannot supply the missing frame artwork. Likewise, selecting a named device profile affects emulation settings, not the appearance of the final canvas.
Wait for the right page state
The example waits for networkidle0, but there is no single wait condition that is correct for every site. Pages may continue network activity because of analytics, streaming updates, or other background requests, while a page may appear loaded before a particular image or component is ready. Choose a wait that corresponds to the page’s actual content and capture requirement. If a key element matters, waiting for that selector can be more targeted than waiting for all network activity to stop.
- Capture looks incomplete: wait for the relevant selector or content state before taking the screenshot.
- Navigation never reaches the wait condition: use a condition appropriate to the site rather than assuming network idle is universal.
- Lazy-loaded content is missing: consider whether the page needs scrolling or another trigger before capture; verify the result rather than assuming navigation alone loads everything.
- Image is blank or blocked: inspect the site’s availability, browser console or network behavior, and access requirements. A screenshot call cannot capture content the page did not successfully render.
Common mistakes and fixes
Expecting emulation to draw a bezel
Cause: confusing a device viewport with a device mockup. Fix: capture the page, then compose it with separate frame artwork or a layout.
Changing to a phone viewport after the page loads
Cause: navigating at desktop dimensions and resizing afterward. Some sites do not expect that transition. Fix: set the viewport or call page.emulate(device) before navigation where possible, as Puppeteer recommends in its emulation documentation.
Free tools Windows power users keep installed
One-click scans. No signup required.
The screenshot has the wrong sharpness or dimensions
Cause: mixing CSS-pixel viewport dimensions with output-pixel dimensions, or scaling the image during composition. Fix: check the viewport and deviceScaleFactor settings, then confirm the final canvas dimensions and aspect ratio. Neither a higher scale factor nor a larger canvas creates a hardware border.
The mockup cuts off the content
Cause: using a full-page capture in a screen opening intended for a viewport image, or fitting mismatched aspect ratios. Fix: choose viewport capture for a single-screen mockup, or redesign the composition for the longer full-page image.
The script hangs or captures before a component is ready
Cause: a wait condition does not match the site’s behavior. Fix: choose a page-state wait suited to the target and wait explicitly for critical content where practical. Keep the capture step after the readiness check.
The code works locally but not in another environment
Cause: Puppeteer and its browser/runtime setup are version- and environment-sensitive. Fix: use a compatible installed Puppeteer package, check the API documentation for that version, and make sure the execution environment can launch its browser. The cited screenshot guide is identified as version 25.12.0; the API pages may evolve.
Or skip the browser setup
If your goal is a clean website capture rather than learning Puppeteer’s browser setup, ScreenshotNeo is a website screenshot API and MCP server. It returns an image or PDF from one GET request. It captures page content, not a decorative hardware frame; you would still add a frame asset in a separate composition step.
For API details and options, see the ScreenshotNeo documentation. This cURL request saves a WebP screenshot:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpEquivalent Python:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)Equivalent Node.js:
const q = new URLSearchParams({
access_key: 'YOUR_API_KEY',
url: 'https://example.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);ScreenshotNeo accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; each of those steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info and capture_pdf for AI agents and MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
FAQ
Can Puppeteer take a screenshot in an iPhone frame?
It can emulate device viewport and user-agent settings, but the documented APIs do not add an iPhone bezel. Capture the page and make the framed mockup as a separate composition.
Does deviceScaleFactor add a border around the screenshot?
No. It is a viewport/device scale property, not a decorative frame control.
Can I capture just one element instead of the whole page?
Yes. Puppeteer’s element screenshot method captures an element handle; use it when that element, rather than the viewport or full document, is the material you need.
Quick Recap
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.
Recommended Free Tools
