FileUpload

Applications that handle user uploads quickly accumulate custom drag-and-drop logic, file validation, size constraints, and competing representations (list vs. thumbnails) scattered across forms and dashboards. Without a single source of truth, you end up reimplementing file picker logic, forgetting to revoke object URLs, duplicating remove buttons, and drifting state management when a designer wants the thumbnail grid to switch to list mode.

FileUpload is a controlled compound component with a root that manages file state, plus two display subcomponents: FileUpload.Dropzone (drag-and-drop + click-to-browse) and FileUpload.List (two-mode display: detailed list or image-thumbnail grid). The root accepts value (File[]) and onChange for controlled state, accept (an HTML accept string), multiple, maxFiles and maxSize for constraints, and disabled for blocking all upload/removal. accept is enforced on the drop path as well as in the browse dialog, which the browser does not do for you. Stable data attributes on the wrapper and each subcomponent make the surface agent-readable.

Import FileUpload from @particle-academy/react-fancy, wrap a Dropzone and List subcomponent, and pass value and onChange to track files: <FileUpload value={files} onChange={setFiles}><FileUpload.Dropzone /><FileUpload.List thumbnail /></FileUpload>. Agents can read the current file state via the files context property and call addFiles or removeFile through a bridge exposing useFileUpload.