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, maxFiles and maxSize for constraints, and disabled for blocking all upload/removal. 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.