Use Puppeteer’s page.mouse.dragAndDrop(start, target, options?) method to perform a drag-and-drop gesture between two viewport points. Find the source and destination with locators, read their bounding boxes, and pass suitable coordinates to the mouse API. Then verify that the page’s state changed: sending the gesture does not guarantee the application accepted the drop.
Drag and drop between two elements
The current documented mouse API takes points, not selectors or element handles. Puppeteer recommends locators for finding elements and managing readiness; use the lower-level mouse API for the drag gesture when the locator API does not provide the action you need. See the Puppeteer page interactions guide and the Mouse.dragAndDrop API reference.
As an Amazon Associate I earn from qualifying purchases.
Here is a complete Node.js example. Replace the URL and selectors with those for your page. It assumes the page has an element with ID source and a drop target with ID target.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({ headless: true });
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
const source = await page.locator('#source').boundingBox();
const target = await page.locator('#target').boundingBox();
if (!source || !target) {
throw new Error('Source or target is not visible in the layout');
}
await page.mouse.dragAndDrop(
{
x: source.x + source.width / 2,
y: source.y + source.height / 2,
},
{
x: target.x + target.width / 2,
y: target.y + target.height / 2,
},
{ delay: 100 },
);
// Check the page's actual post-drop state here.
console.log('Drag gesture completed; verify the resulting page state.');
} finally {
await browser.close();
}
})();Install Puppeteer in your project with npm install puppeteer, save the example as a JavaScript file, and run it with node filename.js. If your page requires authentication or a specific setup, establish that state before measuring the elements.
#1 Best Overall
Choose the points deliberately
The example uses the center of each bounding box as a starting point. That is only a reasonable default: a draggable item may need to be grabbed by a handle, and a drop zone may accept input only within a particular region. Adjust the coordinates to match the page’s actual hit areas.
Wait for the page before measuring
Locators wait for an element to be present and ready for an action, but a bounding box can still be absent when an element has no visible layout box. If the page reveals the controls only after another action or asynchronous work, wait for that state before calling boundingBox(). Confirm that each locator identifies the intended element.
What Puppeteer’s drag operation does
page.mouse exposes Puppeteer’s mouse API. Its coordinates are CSS pixels relative to the main frame’s viewport, measured from the viewport’s top-left corner—not document coordinates. The API defines dragAndDrop(start, target, options?) as a sequence of drag, dragenter, dragover, and drop events. Its optional delay is the wait in milliseconds between dragover and drop; the default is zero. See the Puppeteer Mouse class reference.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Puppeteer’s mouse events are synthetic. The documentation cautions that they do not fully reproduce everything a user can do with a physical mouse; for example, text selection cannot be performed with page.mouse. A drag sequence may therefore behave differently from the gesture expected by a particular application.
Verify the drop by checking application state
Do not treat a completed call to dragAndDrop() as proof that the page accepted the drop. Check the outcome the application is supposed to produce—for example, whether the item now belongs to the destination container or whether its position in a list changed. The right assertion depends on the page; avoid relying only on a log message that the gesture ran.
Current API versus the obsolete ElementHandle method
Use the coordinate-based page.mouse.dragAndDrop() method for this pattern: identify the elements, calculate points, then perform the gesture. The older ElementHandle.dragAndDrop() API reference is marked obsolete and directs readers to ElementHandle.drop instead. Do not start a new example with the obsolete method. See the obsolete ElementHandle.dragAndDrop reference.
Rank #3
Troubleshooting
One of the bounding boxes is null
The element may not have a visible layout box, or the locator may not match the intended element. Wait until the relevant page state is ready, check the selector, and make sure the element is visible before measuring.
Crashes, 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 minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11The gesture runs but the drop is ignored
Check whether the starting point lands on the draggable part of the element and whether the destination point is inside the real drop zone. A center point may miss either one. Also check the application’s expected resulting state rather than assuming that emitted events were accepted.
The application expects a different gesture
The documented method performs a drag-event sequence, while Puppeteer’s mouse events are synthetic. If the page uses a custom interaction, inspect what that interaction expects and verify that the chosen API matches it. The documentation does not promise that every application’s drag behavior will respond identically.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
The page needs time before dropping
Pass a positive delay in milliseconds when the page needs a pause between dragover and drop; for example, { delay: 100 }. The documented default is zero, so the API does not wait between those events unless you request it.
An existing snippet calls ElementHandle.dragAndDrop()
That method is marked obsolete in the API documentation. For a coordinate-based drag, use page.mouse.dragAndDrop() with points derived from the current element positions.
Or skip the browser setup
ScreenshotNeo is a website screenshot API, not a replacement for Puppeteer’s drag-and-drop interaction. If you need a screenshot of the page after your own automation, you can request an image with one GET call; see the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never 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. Learn about ScreenshotNeo or sign up for 1,000 free screenshots a month with no card.
Frequently Asked Questions
Can I pass CSS selectors directly to page.mouse.dragAndDrop()?
No. The method takes start and target points; use element locations to calculate those coordinates.
Does Puppeteer guarantee a drag will work in every web app?
No. Its mouse events are synthetic, and applications can implement drag behavior differently.
Free tools Windows power users keep installed
One-click scans. No signup required.
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.
