// blog
Drag and Drop a DICOM Folder Into a Web Page
A dropped folder arrives as an empty file, so read the drop’s items as entries while the event lasts, then walk each directory with readEntries until it returns an empty batch. Open ZIPs in the browser, keep only DICOM files, group them by Series Instance UID, and sort the largest series by position. In an embedded viewer, listen on the window too, so a drop anywhere in the frame opens the files instead of the browser navigating to them.

A patient CD has a folder called DICOM with hundreds of files named like IM000123, no extensions, sometimes in nested folders, plus a DICOMDIR and a Windows viewer. People want to drag that folder onto a page and see the scan. Our DICOM viewer does, and since it’s now embedded in other websites, it does it anywhere in its frame. Here’s what that takes.
1. Take the entries during the drop
A dropped folder shows up in dataTransfer.files as one file of size zero. The contents are behind the item’s entry:
const onDrop = (e) => {
e.preventDefault();
// Now, while the event lasts: afterwards dataTransfer is empty.
const entries = [...e.dataTransfer.items].map((it) => it.webkitGetAsEntry?.() ?? null);
if (entries.some((x) => x?.isDirectory)) filesIn(entries).then(open);
else open(e.dataTransfer.files);
};
The prefix is history: webkitGetAsEntry works in every current desktop browser.
2. Walk the folders, in batches
async function filesIn(entries) {
const out = [];
const walk = async (entry) => {
if (entry.isFile) return out.push(await new Promise((ok, fail) => entry.file(ok, fail)));
if (!entry.isDirectory) return;
const reader = entry.createReader();
for (;;) {
const batch = await new Promise((ok, fail) => reader.readEntries(ok, fail));
if (!batch.length) break; // readEntries gives ~100 at a time: keep asking
for (const child of batch) await walk(child);
}
};
for (const entry of entries) if (entry) await walk(entry);
return out;
}
The loop is the part most examples leave out. One call to readEntries returns a batch, about 100 entries in Chrome. A series of 300 slices then opens with a third of its images, and nothing says so.
3. Open ZIPs in the browser
A downloaded study is usually a ZIP. Check the first four bytes (PK\x03\x04), not the name, and inflate it in the tab with the browser’s own DecompressionStream, read in chunks. Then read its entries like any other files. Stop at a ceiling on the total inflated size (ours is 600 MB), so a damaged or hostile ZIP can’t fill the memory.
4. Keep the DICOM files, then pick the series
Not everything in the folder is an image: DICOMDIR, the bundled viewer’s files, a readme. A DICOM file has DICM at byte 128; skip anything without it (older files without that preamble need a looser check).
A CD often holds several series: a scout, the axial series, reformats. The viewer groups the files by Series Instance UID, takes the series with the most images and sorts it by position (Image Position Patient, then Slice Location, then Instance Number). It says how many other files it skipped (not DICOM, or another series), so nobody wonders where the rest went. If nothing at all opens, it says why the first file didn’t.
5. Inside another website: the whole frame is a drop target
Embedded, the viewer is a frame inside someone else’s page. The image and the open box take drops, but a visitor aiming at the frame often lands on the toolbar or the notice above it. Drop a file outside a drop target and the browser opens the file itself, and the viewer is gone.
So the embedded viewer also listens on its window:
window.addEventListener("dragover", (e) => {
if (e.dataTransfer?.types.includes("Files")) e.preventDefault(); // allow the drop here
});
window.addEventListener("drop", (e) => {
if (e.defaultPrevented || !e.dataTransfer?.types.includes("Files")) return; // the image took it already
e.preventDefault();
dropped(e.dataTransfer);
});
The image’s own handler runs first and marks the event handled; the window only takes what fell elsewhere. Checking for "Files" leaves text and links dragged within the page alone.
A drop lands in whichever document is under the pointer, so files dropped on the frame go to the viewer, never to the page around it. The page around it can’t read inside the frame either: it’s another origin.
What it adds up to
Drop a CD’s folder, a ZIP or a handful of files anywhere on the viewer, and the largest series opens, sorted, with every tag. Nothing leaves the tab. Try it on our page, or put it on yours.
How the whole embeddable viewer was built, from the frame to the counts: the case study.
If your own product needs files handled like this, in the browser and without an upload, that’s the kind of thing we build.
Frequently asked questions
Why does a dropped folder look like an empty file?
dataTransfer.files lists a folder as a file of size zero. Its contents are only reachable through the item's entry, from webkitGetAsEntry(), which works in Chrome, Edge, Firefox and Safari despite the prefix.
Why read the entries before anything else?
The drop's dataTransfer is only readable during the drop event. Take the entries first, synchronously; read the files from them afterwards.
Why does readEntries need a loop?
It returns a directory's entries in batches (about 100 at a time in Chrome). Call it again until it returns an empty array, or a series of 300 slices opens with 100.
Is anything uploaded?
No. Every step runs in the browser tab. The files are gone when the visitor closes them or leaves the page.
































































































































