Input File Directory: Browser Support, Usage, Limits

What is Input File Directory?

Input File Directory is the webkitdirectory boolean attribute on the HTML input element with type file. When the attribute is set, the file chooser opens in folder mode, and the page receives every file inside the chosen folder and its subfolders through input.files. Each file also exposes its path through webkitRelativePath.

Which browsers does Input File Directory support?

Every major desktop browser ships the webkitdirectory attribute today, mobile Safari shipped full support in Safari 18.4, and global usage covers more than 95% of page views.

What are the key features of Input File Directory?

The webkitdirectory attribute is small in surface area, but it changes how the file picker, the FileList, and every File object behave. Five features carry the weight of the API.

• Folder picker mode: Setting the attribute switches the native file dialog from file mode to folder mode. The user picks a single folder, and the browser walks every nested file inside it.
• Flat FileList with paths: input.files stays a flat FileList. Each File object also exposes file.webkitRelativePath so you can rebuild the original folder hierarchy on the server side.
• Works alongside multiple: Adding the multiple attribute lets users pick more than one folder on browsers that allow it. The folders merge into one FileList, and webkitRelativePath keeps each folder root in the path.
• Pairs with the accept attribute: The accept attribute filters files by MIME type or extension after the folder walk. The browser still reads the whole folder, then drops files that fail the accept filter from the FileList.
• Progressive enhancement by default: Browsers that do not understand the attribute ignore it and fall back to a normal file picker. The fallback never throws, so you can ship the attribute everywhere without a feature gate.

How do you use Input File Directory in HTML?

You add the webkitdirectory attribute to an input type file, listen for the change event, and read each file plus its webkitRelativePath. Wire up the markup, the script, and a feature-detect once and the same code path covers Chrome, Edge, Firefox, Safari, Opera, and Samsung Internet.

• Drop the markup in your form: Add an input element with type file, the webkitdirectory attribute, and the multiple attribute if you want users to pick more than one folder at a time.
• Detect support before you call it special: Create an input element in JavaScript and check that webkitdirectory is in the element. The check returns false on Internet Explorer and on engines that strip the attribute.
• Listen for the change event: Attach a change listener that reads event.target.files. The listener fires once after the user confirms the folder, never per file.
• Read webkitRelativePath on every file: Loop over input.files and pull file.webkitRelativePath from each File object. The string starts with the folder name and contains forward slashes on every platform.
• Build the upload payload: Append every file to a FormData instance with formData.append("files", file, file.webkitRelativePath) so the server receives the path. Post the FormData with fetch or XMLHttpRequest.
• Confirm with a feature-detect snippet: Run the snippet below in the DevTools console of the target browser before you ship.

The reference markup looks like this:

<input type="file" id="folder-picker" webkitdirectory multiple />
<ul id="file-listing"></ul>

<script>
  const picker = document.getElementById("folder-picker");
  const listing = document.getElementById("file-listing");

  picker.addEventListener("change", (event) => {
    listing.innerHTML = "";
    for (const file of event.target.files) {
      const item = document.createElement("li");
      item.textContent = file.webkitRelativePath + " (" + file.size + " bytes)";
      listing.appendChild(item);
    }
  });
</script>

And the feature-detect snippet you can paste straight into the DevTools console:

// Paste this into the DevTools console to confirm folder picker support.
const probe = document.createElement("input");
probe.type = "file";

if ("webkitdirectory" in probe) {
  console.log("Folder upload via webkitdirectory is supported.");
} else {
  console.log("This browser does not expose the webkitdirectory attribute.");
}

What are the known issues with Input File Directory?

Folder upload looks simple, but the attribute carries a stack of cross-browser quirks around mobile pickers, drag-and-drop, and path handling.

• iOS Safari folder picker is iCloud-bound: Safari 11.3 to 18.3 on iOS only let users pick folders from iCloud Drive. Safari 18.4 and later widen the picker to the on-device Files app, but local app folders may still be hidden.
• Android folder picker varies by OEM: The Android system picker maps to the Storage Access Framework, and OEMs ship different SAF surfaces. Test on Pixel, Samsung, and Xiaomi devices because the chooser layout and the visible roots can differ.
• Drag-and-drop bypasses the input: Dropping a folder onto the input fires a drop event, not a change event. Read dataTransfer.items and call DataTransferItem.webkitGetAsEntry to walk the dropped folder.
• Symlinks and hidden files leak: Chrome and Firefox follow symbolic links inside the chosen folder and include hidden dotfiles. Filter on the client before you upload to keep node_modules or .git out of the payload.
• Large folders block the main thread: The browser walks every file synchronously before the change event fires. Folders with tens of thousands of files freeze the picker on low-end devices, so guide users to small subfolders.
• Backslashes never appear in the path: webkitRelativePath always uses forward slashes, even on Windows. Server code that splits on path.sep needs to normalize first.
• The attribute is non-standard: webkitdirectory is not in the HTML Standard at the WHATWG. Future engine changes are possible, and accessibility tools may not announce the folder mode to screen reader users.

In my experience, the silent killer is the iOS picker change. A flow that worked perfectly on macOS Safari and a recent iPhone broke on an older iPad because the iCloud-only chooser hid the folder users wanted to pick. Always test on a real device that matches the iOS version your users actually run, not the latest one.

Citations

All Input File Directory version numbers and platform notes in this guide come from these primary sources:

• MDN Web Docs - HTMLInputElement.webkitdirectory: developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/webkitdirectory
• MDN Web Docs - File.webkitRelativePath: developer.mozilla.org/en-US/docs/Web/API/File/webkitRelativePath
• MDN Web Docs - input type file element: developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/file
• WICG - File and Directory Entries API: wicg.github.io/entries-api
• web.dev - Open a directory pattern: web.dev/patterns/files/open-a-directory
• Smashing Magazine - Uploading Directories With webkitdirectory: smashingmagazine.com/2017/09/uploading-directories-with-webkitdirectory
• Chrome Platform Status - directory upload: chromestatus.com/feature/5694298997948416
• WebKit Bugzilla - webkitdirectory attribute: bugs.webkit.org/show_bug.cgi?id=161305
• Mozilla Hacks - Firefox 50 release notes: mozilla.org/en-US/firefox/50.0/releasenotes
• Apple Developer - Safari 11.1 Release Notes: developer.apple.com/documentation/safari-release-notes/safari-11_1-release-notes
• makandra dev - HTML file inputs support picking directories: makandracards.com/makandra/54804-html-file-inputs-support-picking-directories