Use await page.mouse.wheel({deltaY: 100}) to send a downward mouse-wheel event in Puppeteer. A negative deltaY requests upward movement. Await the call before running steps that depend on the scroll.
Scroll the page with page.mouse.wheel()
Call wheel() on the page’s mouse object, passing the vertical scroll amount as deltaY:
As an Amazon Associate I earn from qualifying purchases.
await page.mouse.wheel({deltaY: 100});Puppeteer’s API describes this method as dispatching a mousewheel event. The returned value is a promise, so use await in an async function. Puppeteer: Mouse.wheel()
Scroll up or down
deltaY: 100requests downward movement.deltaY: -100requests movement in the opposite direction; Puppeteer’s official example uses this negative value.
The amount is an input to a wheel event, not a guarantee that the page will move by exactly that many pixels. Page behavior, scroll position, and the element under the pointer can affect the result.
#1 Best Overall
Minimal runnable example
This example assumes you have already created a Puppeteer page and navigated it to the page you want to control:
async function scrollDown(page) {
await page.mouse.wheel({deltaY: 100});
}
await scrollDown(page);For a complete browser flow, put the call inside an async function after navigation:
Rank #2
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});
} finally {
await browser.close();
}
})();Scroll a specific element with a locator
When the target is a particular scrollable element, Puppeteer’s interactions guide documents locator-based scrolling:
await page.locator('div').scroll({
scrollLeft: 10,
scrollTop: 20,
});Replace div with a selector that identifies 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 visibility, and waits for a stable bounding box over two consecutive animation frames. See Puppeteer: Page interactions.
Choose the method by what you need to control
| Method | Target | Use it when |
|---|---|---|
page.mouse.wheel({deltaY}) |
Wheel input through the page mouse | Your automation needs to dispatch a wheel event. |
page.locator(selector).scroll({scrollLeft, scrollTop}) |
A selected element | You want locator-based scrolling and its visibility and stability preconditions. |
page.evaluate(...) |
Page context and DOM state | You need to change or inspect scroll state directly rather than send wheel input. |
Wheel input versus changing scroll state directly
page.evaluate() runs a function in the page context and returns its result. It is a different mechanism from page.mouse.wheel(): use wheel input when the behavior under test or automation depends on receiving a wheel event; use page-context code when the goal is to manipulate scroll state directly. The Page.evaluate() API documents the page-context approach.
Coordinate and event caveats
Puppeteer’s mouse works in main-frame CSS pixels relative to the viewport’s top-left corner. Its events are synthetic and do not fully reproduce a real user’s mouse behavior. If the page depends on detailed input behavior, validate the result in the browser and page relevant to your automation rather than assuming synthetic input matches a physical mouse. See Puppeteer: Mouse class.
Troubleshoot wheel scrolling
- The next action runs too soon: make the wheel call asynchronous and await it before continuing.
- The page does not appear to move: check that the page or intended element can scroll in that direction, and that the pointer is positioned where the page expects wheel input. A wheel event does not guarantee movement.
- You meant to scroll a nested panel: target that element with
page.locator(selector).scroll(...)instead of assuming page-level wheel input will affect the intended container. - The application responds differently than a real user session: Puppeteer’s mouse events are synthetic; verify the interaction in the relevant browser and page.
Or skip the browser setup
ScreenshotNeo captures a page as an image or PDF; it does not send Puppeteer mouse-wheel input or test scroll-triggered behavior. If your goal is a screenshot rather than automating scrolling, one GET request can return a capture. This example saves the response as WebP:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsQuick Recap
Best Value
- Used Book in Good Condition
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are not billed. It also provides an MCP server for AI agents to take screenshots. 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.
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.
