{"id":13182,"library":"file-drops","title":"Browser File Drop Utility","description":"File-drops is a straightforward, in-browser utility designed to simplify handling file drop events within web applications. It abstracts away the complexities of browser drag-and-drop APIs, allowing developers to easily register a drop handler on any DOM element. When files are dropped, the utility processes them, providing an array of objects containing file `name` and `contents`. The current stable version is `0.7.0`. The package generally sees maintenance updates for dependency bumps or minor fixes, with a significant architectural shift in `v0.6.0` which transitioned it to an ES module-only distribution and introduced official TypeScript type definitions, dropping legacy UMD support. Its primary differentiator lies in its focused scope and minimal API, providing a lean solution for file input without encompassing broader UI components or file system interactions, making it highly suitable for applications requiring only direct file content access upon a user drop.","status":"active","version":"0.7.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/nikku/file-drops","tags":["javascript","browser","file-drop","typescript"],"install":[{"cmd":"npm install file-drops","lang":"bash","label":"npm"},{"cmd":"yarn add file-drops","lang":"bash","label":"yarn"},{"cmd":"pnpm add file-drops","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Internal DOM manipulation utility, regularly updated as a runtime dependency.","package":"min-dom","optional":false}],"imports":[{"note":"The package migrated to ES Modules (ESM) in v0.6.0, dropping CommonJS (CJS) and UMD distributions. Direct `require()` statements will fail.","wrong":"const fileDrop = require('file-drops');","symbol":"fileDrop","correct":"import fileDrop from 'file-drops';"},{"note":"TypeScript types are available since v0.6.0 and should be imported as types.","symbol":"FileDropHandler","correct":"import type { FileDropHandler } from 'file-drops';"},{"note":"TypeScript types are available since v0.6.0 for the structure of returned file objects.","symbol":"FileContent","correct":"import type { FileContent } from 'file-drops';"}],"quickstart":{"code":"import fileDrop from 'file-drops';\n\nconst container = document.createElement('div');\ncontainer.id = 'container';\ncontainer.style.width = '300px';\ncontainer.style.height = '200px';\ncontainer.style.border = '2px dashed #ccc';\ncontainer.style.display = 'flex';\ncontainer.style.alignItems = 'center';\ncontainer.style.justifyContent = 'center';\ncontainer.textContent = 'Drag files here';\ndocument.body.appendChild(container);\n\nconst dropHandler = fileDrop('Drop a file', function(files) {\n console.log('Files dropped:', files);\n files.forEach(file => {\n console.log(`File Name: ${file.name}`);\n console.log(`File Contents (first 100 chars): ${file.contents.substring(0, 100)}`);\n });\n});\n\ncontainer.addEventListener('dragover', dropHandler);\ncontainer.addEventListener('drop', dropHandler);\n\n// Example of how to style the overlay (requires CSS for .drop-overlay, .box, .label)\n// document.head.insertAdjacentHTML('beforeend', `\n// \n// `);\n","lang":"javascript","description":"Demonstrates how to initialize a file drop area on a DOM element and handle the dropped files, logging their names and contents."},"warnings":[{"fix":"Update all module imports to use ES Module syntax (e.g., `import fileDrop from 'file-drops';`). Ensure your project's build tooling supports ESM.","message":"Version 0.6.0 dropped UMD distribution and migrated the package to ES Modules (ESM). Projects using CommonJS `require()` statements will break.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Ensure `element.addEventListener('dragover', dropHandler);` and `element.addEventListener('drop', dropHandler);` are both used on the target DOM element.","message":"The `dropHandler` function returned by `fileDrop` must be attached to both `dragover` and `drop` events to correctly handle the drag-and-drop interaction, including preventing default browser behavior.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"If specific handling is needed for file types (e.g., `ArrayBuffer` for images), consider using a different library or converting the string content manually post-drop. The library focuses on simplicity and text-based content retrieval.","message":"The package returns file contents as a string. For binary files or large files, this might not be the most efficient or desired format. Developers need to handle parsing or conversion themselves.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change your import statement from `const fileDrop = require('file-drops');` to `import fileDrop from 'file-drops';`.","cause":"Attempting to use `require()` to import `file-drops` in a project configured for ES Modules, or after upgrading to `file-drops` v0.6.0+.","error":"ReferenceError: require is not defined"},{"fix":"Ensure `fileDrop` is called with both a label string and a callback function, e.g., `fileDrop('Drop a file', function(files) { /* ... */ });`.","cause":"The `fileDrop` function's second argument (the callback) is missing or not a function, leading to an invalid event listener argument.","error":"Uncaught TypeError: Failed to execute 'addEventListener' on 'EventTarget': 2 arguments required, but only 1 present."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}