To drag an element with Puppeteer’s low-level mouse API, move to a point on the source, press the mouse button, move to a point on the destination while holding the button, then release it. Use page.mouse.dragAndDrop() instead when you want Puppeteer’s documented drag-and-drop event sequence.
Drag an element with mouse coordinates
This example uses locators to find the source and destination, then uses their bounding boxes to calculate center points. Change those points if the control responds to a particular drag handle rather than its center.
const sourceBox = await page.locator('[data-testid="source"]').boundingBox();
const targetBox = await page.locator('[data-testid="target"]').boundingBox();
if (!sourceBox || !targetBox) {
throw new Error('Drag source or target is not in layout');
}
const source = {
x: sourceBox.x + sourceBox.width / 2,
y: sourceBox.y + sourceBox.height / 2,
};
const target = {
x: targetBox.x + targetBox.width / 2,
y: targetBox.y + targetBox.height / 2,
};
await page.mouse.move(source.x, source.y);
await page.mouse.down();
await page.mouse.move(target.x, target.y, { steps: 10 });
await page.mouse.up();The sequence matters: the button must remain down during the movement. The steps option adds intermediate movements between the current point and destination; its documented default is 1. More steps can help when an application responds to movement along a path, but no particular count guarantees that a given page will accept the drag.
What the coordinates mean
page.mouse uses main-frame CSS pixels measured from the viewport’s top-left corner. The bounding boxes in the example are relative to the main frame, and boundingBox() returns null when an element is not part of the layout. The null check prevents trying to use missing coordinates.
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 glitches#1 Best Overall
The center is only a practical starting point, not a Puppeteer requirement. For sortable lists, sliders, or custom widgets, use a point inside the actual drag handle. Make sure the source and target are visible and positioned as expected before calculating coordinates.
Use Puppeteer’s drag-and-drop helper when appropriate
For a shorter alternative, Puppeteer documents a page mouse helper that performs drag, dragenter, dragover, and drop in sequence:
Rank #2
await page.mouse.dragAndDrop(source, target);Here, source and target are coordinates in the same viewport-relative CSS-pixel coordinate system. The optional delay setting controls the wait between dragover and drop; the documented default is zero. Use the manual sequence when you need direct control over pointer movement, and the helper when its event sequence fits the page’s expected interaction.
Do not confuse this with page.mouse.drag(start, target): that API dispatches a drag event and returns drag data, but is not documented as the complete drag-enter/over/drop sequence.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Select elements and check readiness
Puppeteer recommends locators for selecting elements and interacting with them because locators wait for elements and apply readiness checks. The interaction guide describes checks including viewport presence, visibility, enabled state, and a stable bounding box for clicking. For a custom coordinate drag, use a locator to identify the elements, then obtain their boxes and confirm the chosen points match the page’s drag behavior.
Older or alternative ElementHandle helper signatures need extra care: the current next ElementHandle reference marks dragAndDrop deprecated, and the specific ElementHandle API reference calls it obsolete and points to drop. The references carry different version labels, so consult the documentation matching your installed Puppeteer version before relying on an ElementHandle helper.
Rank #4
Why a drag can fail
Mouse input in Puppeteer consists of synthetic MouseEvents and does not fully reproduce normal user mouse behavior. Puppeteer specifically warns that dragging and selecting text are not possible using page.mouse. A page that depends on native HTML drag-and-drop behavior or framework-specific pointer or touch input may therefore react differently from a person’s gesture.
- The source or target has no box:
boundingBox()can returnnullwhen an element is not in layout. Wait for the relevant UI to appear and check that the element remains attached before using its coordinates. - The drag starts from the wrong place: Try a point on the control’s drag handle rather than the element center.
- The page does not accept the drop: Check whether it expects HTML drag-and-drop events or a different pointer or touch interaction. If appropriate, try the documented
dragAndDrophelper rather than only a manual mouse move. - The movement is too abrupt for the UI: Use the manual sequence with intermediate
steps. This changes the path’s granularity; it does not guarantee success. - The calls complete but nothing changes: Verify the resulting DOM or visible state. Completing the input calls does not prove the application accepted the drop.
Or skip the browser setup
ScreenshotNeo takes website screenshots; it does not perform Puppeteer drag interactions or replace this drag code. If you already have the page in its desired state and need a screenshot, one GET request can capture it:
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →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. Before capture, it accepts cookie or consent banners and removes 60+ known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
Should I use page.mouse.dragAndDrop() or manual mouse calls?
Use the helper for its documented drag, dragenter, dragover, and drop sequence; use manual calls when you need control over coordinates and pointer movement.
Does increasing steps guarantee that a drag will work?
No. It adds intermediate mouse movements, but the page’s event model and drag behavior determine whether the drop is accepted.
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.
Free tools Windows power users keep installed
One-click scans. No signup required.
