File Upload

@allem-ui/file-upload

Drag-and-drop file upload with image previews, progress tracking, and validation.

Installation

npm install @allem-ui/file-upload

Add the @source directive to your CSS so Tailwind generates the component classes:

@source "@allem-ui/file-upload";

Drop Zone

Drag files onto the zone or click to browse. Supports type, size, and count validation.

Click to upload or drag and drop

image/*, .pdf

Custom Trigger

Use FileUploadTrigger to wrap any element as an upload button.

With Validation

Restrict to 2 files, max 1 MB each, only .png and .jpg. Files that exceed limits show an error state.

Click to upload or drag and drop

.png, .jpg

FileUpload Props

Prop	Type	Default	Description
onFilesSelected*	(files: File[]) => void	—	Called with selected files
accept	string	—	Accepted file types (e.g. "image/*,.pdf")
multiple	boolean	true	Allow multiple files
maxFiles	number	—	Maximum number of files — shows count indicator when set
currentCount	number	0	Current number of files — used with maxFiles for the count display
maxSize	number	—	Maximum file size in bytes — shows size hint in the drop zone
disabled	boolean	false	Disable the drop zone
className	string	—	Additional CSS classes
children	ReactNode	—	Custom drop zone content

FileUploadItem Props

Renders a single file row with thumbnail preview (for images), file icon with type-based coloring, progress bar, and status indicator. Used internally by FileUploadList — import it directly for custom list layouts.

Prop	Type	Default	Description
file*	UploadFile	—	The file object to display
onRemove	(id: string) => void	—	Callback when remove button is clicked
className	string	—	Additional CSS classes

FileUploadList Props

Prop	Type	Default	Description
files*	UploadFile[]	—	Array of files to display
onRemove	(id: string) => void	—	Callback when a file is removed
className	string	—	Additional CSS classes

FileUploadTrigger Props

Prop	Type	Default	Description
onFilesSelected*	(files: File[]) => void	—	Called with selected files
accept	string	—	Accepted file types
multiple	boolean	true	Allow multiple files
disabled	boolean	false	Disable the trigger
children*	ReactNode	—	Custom trigger element

useFileUpload

Hook that manages file state, validation, and image previews.

Options

Prop	Type	Default	Description
maxFiles	number	—	Maximum number of files
maxSize	number	—	Maximum file size in bytes
accept	string[]	—	Accepted types (e.g. ["image/*", ".pdf"])

Return Value

Prop	Type	Default	Description
files	UploadFile[]	—	Current array of managed files
addFiles	(files: File[]) => RejectedFile[]	—	Add files with validation — returns rejected files
removeFile	(id: string) => void	—	Remove a file by ID
updateProgress	(id: string, progress: number) => void	—	Update upload progress (0–100)
setStatus	(id: string, status: Status, error?: string) => void	—	Set file status ("idle" \| "uploading" \| "success" \| "error")
clearFiles	() => void	—	Remove all files
rejectedFiles	RejectedFile[]	—	Files rejected from the last addFiles() call

Built-in Behavior

Feature	Description
Keyboard accessible	Enter/Space triggers file selection on both FileUpload and FileUploadTrigger.
Image previews	Object URLs are automatically generated for image files and revoked on removal.
Type-based file icons	FileUploadItem shows color-coded icons — emerald for images, red for PDFs, purple for videos.
Smart validation	Supports wildcard MIME matching (image/*), exact MIME, and extension matching (.pdf).

UploadFile Type

Prop	Type	Default	Description
id	string	—	Unique file identifier
file	File	—	Native File object
name	string	—	File name
size	number	—	File size in bytes
type	string	—	MIME type
preview	string	—	Preview URL for images
progress	number	—	Upload progress (0–100)
status	"idle" \| "uploading" \| "success" \| "error"	—	Current upload status
error	string	—	Error message when status is error

RejectedFile Type

Returned by addFiles() for files that failed validation. Use this to show feedback (e.g. toast notifications).

Prop	Type	Default	Description
file	File	—	The native File object that was rejected
reason	"type" \| "size" \| "limit"	—	Why the file was rejected — wrong type, too large, or file count exceeded