useState(false);
const [droppedFiles, setDroppedFiles] = useState([]);
const [error, setError] = useState("");
const inputRef = useRef(null);
const validateFiles = useCallback(
(files) => {
if (!multiple && files.length > 1) {
setError("Only one file is allowed.");
return false;
}
if (accept !== "*") {
const allowedTypes = accept.split(",").map((t) => t.trim());
const allValid = Array.from(files).every((file) =>
allowedTypes.some((type) => file.type === type || file.name.endsWith(type))
);
if (!allValid) {
setError(Invalid file type. Allowed: ${accept});
return false;
}
}
setError("");
return true;
},
[accept, multiple]
);
const handleFiles = useCallback(
(files) => {
const fileArray = Array.from(files);
if (!validateFiles(fileArray)) return;
setDroppedFiles(fileArray);
if (onFilesSelected) onFilesSelected(fileArray);
},
[validateFiles, onFilesSelected]
);
const handleDragOver = (e) => {
e.preventDefault();
e.stopPropagation();
setIsDragging(true);
};
const handleDragLeave = (e) => {
e.preventDefault();
e.stopPropagation();
setIsDragging(false);
};
const handleDrop = (e) => {
e.preventDefault();
e.stopPropagation();
setIsDragging(false);
const files = e.dataTransfer.files;
if (files && files.length > 0) {
handleFiles(files);
}
};
const handleClick = () => {
inputRef.current?.click();
};
const handleInputChange = (e) => {
const files = e.target.files;
if (files && files.length > 0) {
handleFiles(files);
}
};
const handleRemoveFile = (index) => {
const updated = droppedFiles.filter((_, i) => i !== index);
setDroppedFiles(updated);
if (onFilesSelected) onFilesSelected(updated);
};
return (
<div className="w-full max-w-xl mx-auto">
{/* Dropzone Area /}
<div
onDragOver={handleDragOver}
onDragLeave={handleDragLeave}
onDrop={handleDrop}
onClick={handleClick}
className={ flex flex-col items-center justify-center border-2 border-dashed rounded-2xl p-10 cursor-pointer transition-all duration-300 ${isDragging ? "border-orange-400 bg-orange-50 scale-[1.02]" : "border-gray-300 bg-gray-50 hover:border-orange-300 hover:bg-orange-50" } }
>
{/ Icon */}
<div className="mb-4 text-5xl select-none">
{isDragging ? "📂" : "📁"}
</div>
{/* Text */}
<p className="text-gray-600 text-base font-medium text-center">
{isDragging
? "Release to drop your files here!"
: "Drag & drop files here, or click to browse"}
</p>
<p className="text-gray-400 text-sm mt-1 text-center">
{accept === "*" ? "All file types accepted" : `Accepted: ${accept}`}
</p>
{/* Hidden File Input */}
<input
ref={inputRef}
type="file"
accept={accept}
multiple={multiple}
className="hidden"
onChange={handleInputChange}
/>
</div>
{/* Error Message */}
{error && (
<p className="mt-3 text-sm text-red-500 font-medium text-center">
⚠️ {error}
</p>
)}
{/* File List */}
{droppedFiles.length > 0 && (
<ul className="mt-4 space-y-2">
{droppedFiles.map((file, index) => (
<li
key={index}
className="flex items-center justify-between bg-white border border-gray-200 rounded-xl px-4 py-3 shadow-sm"
>
<div className="flex items-center gap-3 overflow-hidden">
<span className="text-xl">📄</span>
<div className="overflow-hidden">
<p className="text-sm font-medium text-gray-700 truncate">{file.name}</p>
<p className="text-xs text-gray-400">{(file.size / 1024).toFixed(1)} KB</p>
</div>
</div>
<button
onClick={(e) => {
e.stopPropagation();
handleRemoveFile(index);
}}
className="ml-4 text-gray-400 hover:text-red-500 transition-colors text-lg font-bold"
aria-label="Remove file"
>
×
</button>
</li>
))}
</ul>
)}
</div>
);
}
**Usage Example**:
// pages/index.jsx or app/page.jsx
import Dropzone from "@/components/Dropzone";
export default function Home() {
const handleFiles = (files) => {
console.log("Selected files:", files);
// Send to server, preview, etc.
};
return (
<main className="min-h-screen flex items-center justify-center bg-gray-100 p-6">
<Dropzone
onFilesSelected={handleFiles}
accept="image/png, image/jpeg, image/webp"
multiple={true}
/>
</main>
);
}
**Technical Implementation Breakdown**:
- `"use client"`: Explicitly marks the component as client-side in Next.js App Router, preventing server-component hydration errors when using `useState`, `useRef`, and DOM event listeners.
- **Hooks Strategy**: `useState` tracks drag state, file array, and validation errors. `useRef` creates a stable reference to the hidden `<input>` for programmatic click triggering. `useCallback` memoizes validation and file-handling functions to prevent unnecessary re-renders and maintain stable dependency arrays.
- **Props Interface**: `onFilesSelected` (callback), `accept` (MIME/type string, defaults to `"*"`), `multiple` (boolean, defaults to `false`).
- **Validation Logic**: `validateFiles` checks file count constraints, splits accepted types, and validates against both `file.type` (MIME) and `file.name` (extension fallback) to handle browsers that return empty MIME types.
- **Event Flow**: `handleDragOver`/`handleDragLeave` toggle visual state. `handleDrop` extracts `e.dataTransfer.files`, prevents default browser navigation, and routes to `handleFiles`. `handleInputChange` mirrors drop behavior for click-to-browse. `handleRemoveFile` filters the array immutably and syncs state with the parent callback.
- **UI/UX**: Tailwind classes manage responsive layout, drag-state transitions (`scale-[1.02]`, color shifts), and accessible truncation for long filenames.
## Pitfall Guide
1. **Missing `e.preventDefault()` on Drag Events**: Browsers default to opening/dropping files as navigation. Without `preventDefault()` on `dragover` and `drop`, the dropzone will fail to capture files and may navigate away from the page.
2. **Omitting `"use client"` in Next.js App Router**: Using `useState`, `useRef`, or DOM listeners inside a server component triggers hydration mismatches. Always place the directive at the top of the file when building interactive UI components.
3. **Relying Solely on `file.type` for Validation**: Some browsers (especially Safari) return empty strings for `file.type` on certain formats. Always pair MIME validation with `file.name.endsWith()` extension checks to ensure cross-browser accuracy.
4. **Mutating State Directly in File Lists**: Using `push()` or direct index assignment on `droppedFiles` breaks React's change detection. Always use immutable patterns like `filter()`, `map()`, or spread syntax to trigger proper re-renders.
5. **Ignoring Click Fallback for Accessibility**: Drag-and-drop alone excludes keyboard-only and screen reader users. The hidden `<input>` + `inputRef.current.click()` pattern ensures full WCAG compliance and universal interaction support.
6. **Event Propagation Leaks on Remove Buttons**: Clicking a remove button inside the dropzone container can trigger the parent `onClick` handler, reopening the file picker. Always call `e.stopPropagation()` on nested interactive elements.
7. **Overusing `useCallback` Without Stable Dependencies**: Memoizing functions without accurate dependency arrays causes stale closures. Ensure `accept`, `multiple`, and `onFilesSelected` are correctly listed in `useCallback` dependency arrays to reflect prop changes.
## Deliverables
- **Blueprint**: Architecture flow diagram detailing the drag-and-drop state machine, event routing pipeline, and parent-child data synchronization pattern.
- **Checklist**: Pre-deployment validation steps including MIME fallback testing, Next.js client boundary verification, accessibility keyboard navigation audit, and bundle size impact assessment.
- **Configuration Templates**: Ready-to-use Tailwind CSS extension configs for drag-state animations, Next.js `next.config.js` client directive routing examples, and TypeScript prop interface definitions (`DropzoneProps.ts`).
