The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Use await page.locator(selector).scroll({ scrollTop, scrollLeft }) to explicitly scroll a located element with Puppeteer. If your goal is simply to click an off-screen target, you usually do not need a separate scroll call: locator actions ensure the target is in the viewport by default.
Explicitly scroll a located element
Call scroll() on the locator and supply the vertical and/or horizontal offset you want. Puppeteer’s guide says this operation uses mouse wheel events; the options are documented in the LocatorScrollOptions reference.
As an Amazon Associate I earn from qualifying purchases.
await page.locator('#results').scroll({
scrollTop: 240,
scrollLeft: 0,
});Replace #results with a selector for the element whose scrollable area you want to move. Use positive or negative offsets as appropriate to the page’s current position; the example is not a request to scroll the page by an absolute coordinate.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteComplete runnable example
This Node.js example launches Chromium, loads a page containing an overflowing element, scrolls that element, and closes the browser:
#1 Best Overall
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({ headless: true });
try {
const page = await browser.newPage();
await page.setContent(`
<div id="results" style="height: 120px; width: 260px; overflow: auto">
<div style="height: 600px; width: 500px">Scrollable content</div>
</div>
`);
await page.locator('#results').scroll({
scrollTop: 240,
scrollLeft: 40,
});
} finally {
await browser.close();
}
})();Install Puppeteer in the project before running the example, for instance with npm install puppeteer. The official page interactions guide shows the locator scroll pattern.
When a locator action already scrolls for you
Locator actions automatically ensure that their target is in the viewport by default. So for an off-screen button you intend to click, this is ordinarily sufficient:
await page.locator('button.submit').click();Locators are Puppeteer’s recommended way to select and interact with page elements. Their actions retry when the element is not ready and check action preconditions, including visibility, viewport presence, and a stable bounding box over consecutive animation frames, as described in the page interactions guide.
This automatic viewport behavior is a precondition for an action, not a substitute for choosing a particular scroll offset. Use .scroll() when you need to move a scrollable region deliberately.
Disable automatic viewport handling for an action
setEnsureElementIsInTheViewport(false) returns a cloned locator configured not to perform the automatic viewport check/scroll for its action:
const locator = page
.locator('button.submit')
.setEnsureElementIsInTheViewport(false);
await locator.click();The setting defaults to true. Disabling it does not scroll anything; call scroll() separately if explicit movement is still needed. See the method reference.
Rank #3
Choose a selector that identifies the intended element
page.locator(selector) accepts CSS selectors and Puppeteer selector syntax. The API reference documents text, accessibility role and name, XPath, and selector combinations that can cross shadow roots; consult Page.locator() for the supported syntax.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Prefer a selector that uniquely identifies the scrollable element. If a broad selector matches multiple elements or identifies a child rather than the container that actually scrolls, you may move the wrong region or see no useful movement. For dynamic pages, allow the target to become available before acting; locator operations retry when the element is not ready.
How the three scrolling-related operations differ
| Operation | What it does | Use it when |
|---|---|---|
Locator.scroll({ scrollTop, scrollLeft }) |
Scrolls the located element using mouse wheel events and the requested offsets. | You need explicit movement of the locator’s scrollable area. |
| Default locator action behavior | Ensures the action target is in the viewport before the action, by default. | You want to click or interact with an off-screen target and do not need a chosen scroll offset. |
ElementHandle.scrollIntoView() |
Explicitly brings an already-held element handle into view, using the automation protocol client or element.scrollIntoView(). |
Your code already uses an ElementHandle and needs an into-view operation rather than locator-based interaction. |
The lower-level alternative is documented at ElementHandle.scrollIntoView(). These operations have different purposes; do not treat explicit offset scrolling and bringing a target into view as interchangeable.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting
The scroll call runs but the page appears unchanged
- Check whether the locator identifies the scrollable container, rather than a non-scrollable child or a different matching element.
- Confirm the target has content that can scroll in the requested direction. An element with no overflow has nowhere to move.
- Remember that
scrollTopandscrollLeftare offsets for the wheel-based scroll operation, not absolute page coordinates.
A click works without an explicit scroll call
This is expected: locator actions ensure the target is in the viewport by default. Keep the explicit scroll() call only when you need deliberate scrolling beyond that action precondition.
The target is not ready or the action does not proceed
Locators retry when an element is not ready, and actions check readiness conditions such as visibility and a stable bounding box. Verify that the selector matches the intended element and that the page has reached the state in which it should be actionable; the behavior is described in the official guide.
An action no longer performs the expected automatic viewport behavior
Check whether the locator was configured with setEnsureElementIsInTheViewport(false). That option disables the automatic viewport handling for the cloned locator; it does not perform explicit scrolling.
Or skip the browser setup
If your goal is to capture a webpage rather than interact with it in a browser session, ScreenshotNeo provides a website screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF. Its capture flow accepts cookie or consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each of those steps can be turned off.
For a WebP screenshot, put your API key in place of YOUR_API_KEY:
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 documentation for request options. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers identify the page verdict and whether the request was billed. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Frequently Asked Questions
Can Puppeteer scroll horizontally with a locator?
Yes. Pass a horizontal offset with scrollLeft to Locator.scroll().
Does setEnsureElementIsInTheViewport(false) disable Locator.scroll()?
No. It configures the cloned locator’s automatic viewport behavior for actions; explicit scroll() remains a separate operation.
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.
