To scroll a page with Puppeteer’s mouse wheel, call and await page.mouse.wheel(). A positive deltaY requests downward movement; a negative value requests movement upward:
await page.mouse.wheel({deltaY: 100});Scroll the page with wheel input
In a Puppeteer script that already has a page object, use page.mouse.wheel() and wait for its promise to resolve before performing an action that depends on the scroll:
await page.mouse.wheel({deltaY: 100});The method dispatches a mousewheel event. A positive deltaY requests downward movement, while a negative value requests movement in the other direction. See the Puppeteer Mouse.wheel() API.
Runnable example
This example opens a page, requests a downward wheel movement, then reads the page’s vertical scroll position:
#1 Best Overall
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.goto('https://example.com');
await page.mouse.wheel({deltaY: 100});
const scrollY = await page.evaluate(() => window.scrollY);
console.log('Vertical scroll position:', scrollY);
} finally {
await browser.close();
}
})();Replace the example URL with the page you need to automate. The position check is useful for confirming the page’s resulting state; the wheel call itself requests input and does not guarantee that every page will respond by scrolling.
Scroll a particular element with a locator
For an element with its own scrollable area, use the locator interaction API when you want to target that element:
Rank #2
await page.locator('div').scroll({
scrollLeft: 10,
scrollTop: 20,
});Replace div with a selector for the intended element. The locator’s scroll() method uses mouse wheel events. Before scrolling, the locator ensures the target is in the viewport, waits for it to be visible, and waits until its bounding box is stable across two consecutive animation frames. Details are in Puppeteer’s page interactions guide.
Choose the method that matches the behavior you need
| Method | Target | Use it when | Behavior to account for |
|---|---|---|---|
page.mouse.wheel({deltaY}) |
Wheel input at page level | Your automation needs to send wheel input, such as when testing behavior that responds to a wheel event. | The call dispatches a synthetic mousewheel event; a page’s resulting scroll depends on its layout and event handling. |
page.locator(selector).scroll({scrollLeft, scrollTop}) |
The selected locator | You want locator-based scrolling, including for a particular element. | The locator first brings the target into view and waits for visibility and a stable bounding box. |
page.evaluate() with page-side scrolling code |
Whatever page element or scroll state your function addresses | You need to alter scroll state directly rather than send wheel input. | This runs code in the page context; it is a different mechanism from dispatching wheel input. |
Puppeteer describes its mouse coordinates as main-frame CSS pixels relative to the viewport’s top-left corner. Its mouse events are synthetic and do not fully reproduce a real user’s mouse behavior. If detailed input behavior matters to your test, validate it in the browser and page you are automating. See the Puppeteer Mouse class documentation.
Free tools Windows power users keep installed
One-click scans. No signup required.
When to use page.evaluate() instead
Use page.evaluate() when the goal is to change or inspect scroll state by running JavaScript in the page context, rather than testing how a page responds to a wheel event. For example, this directly sets the window’s vertical scroll position:
await page.evaluate(() => window.scrollTo(0, 500));That code does not send mouse wheel input. Puppeteer documents Page.evaluate() as running a function in the page context and returning its result. Choose wheel input when the input event itself is part of what you need to exercise.
Troubleshooting
- The page does not appear to move: Confirm that the page or intended element can scroll and that the pointer interaction reaches the relevant content. Check the resulting scroll position or target state after awaiting the wheel call.
- The wrong area scrolls: A page-level wheel request may not target the element you meant. Select the element with
page.locator(...).scroll()and use a selector that identifies the intended scrollable area. - The next step runs before your scroll call completes: Await
page.mouse.wheel()before checking the page or taking an action that depends on the requested input. - A test behaves differently from a physical mouse: Puppeteer’s mouse events are synthetic. If the page relies on detailed real-device input behavior, verify that behavior in the relevant browser rather than assuming automation input is identical.
- Direct scrolling does not trigger the behavior under test: Setting scroll state through
page.evaluate()is not the same as dispatching a wheel event. Usepage.mouse.wheel()when the event response is what you need to test.
Or skip the browser setup
If you only need a screenshot rather than an interactive wheel test, ScreenshotNeo is a website screenshot API and MCP server. A single request captures a URL as an image or PDF; it is not a substitute for testing wheel-driven behavior in Puppeteer.
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 for request options. ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are not billed. Its MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesSign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
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.
