Forms

File Upload

Uploads files via drag-and-drop or system file picker with validation, status presentation, and removal. Applications own transport and retries.

idle

Usage

import {
	FileUpload,
	FileUploadDropzone,
	FileUploadInput,
	FileUploadItem,
	FileUploadItemName,
	FileUploadItemPreview,
	FileUploadItemProgress,
	FileUploadItemRemove,
	FileUploadItemSize,
	FileUploadItemStatus,
	FileUploadList,
	FileUploadTrigger,
} from "@mizen-labs/ui";

Anatomy

The parts and how they nest, taken from the preview above.

<FileUpload>
	<FileUploadDropzone>
		<FileUploadTrigger />
	</FileUploadDropzone>
	<FileUploadInput />
	<FileUploadList>
		<FileUploadItem>
			<FileUploadItemPreview />
			<FileUploadItemName />
			<FileUploadItemSize />
			<FileUploadItemStatus />
			<FileUploadItemRemove />
			<FileUploadItemProgress />
		</FileUploadItem>
	</FileUploadList>
</FileUpload>

Examples

Drag and drop files here

Error and retry

Simulates a failed upload. Retry the same file without selecting it again.

Disabled upload

Enable selection, then disable the selected upload to check paused progress and blocked actions.

Recommendations

Guidance	Practice
Do	Show accepted formats and size limits before selection. Keep rejection reasons and progress beside each file.

Usage boundaries

Guidance	Boundary
Scope	The application owns transport, cancellation, and retries. Validate file content and limits on the server.

API reference

Public props from @mizen-labs/ui. Use exported prop types for the complete TypeScript contract.

Prop	Type	Default	Description
`accept`	`string`	`—`	Accepted file types specifier string matching file extensions or MIME patterns.
`defaultValue`	`readonly File[]`	`[]`	Initial files array for uncontrolled file upload presentation.
`disabled`	`boolean`	`false`	Disables user interaction across picker trigger, dropzone, and remove actions.
`maxFiles`	`number`	`1`	Maximum number of files allowed in the upload collection.
`maxSize`	`number`	`—`	Maximum allowed file size in bytes for each uploaded file.
`name`	`string`	`—`	Field name submitted with form data on the synchronized native file input.
`value`	`readonly File[]`	`—`	Controlled array of files.
`onValueChange`	`(files: readonly File[], details: FileUploadChangeDetails) => void`	`—`	Callback fired when files are added, dropped, or removed with change details.
`onFileReject`	`(rejections: readonly FileRejection[]) => void`	`—`	Callback fired when files are rejected due to type, size, or count constraints.
`FileUpload`	`FileUploadProps`	`"div"`	Root container providing file upload context, drag-and-drop coordination, and accessibility announcements.
`FileUploadDropzone`	`FileUploadDropzoneProps`	`"div"`	Non-interactive drag-and-drop surface receiving files without pretending to be keyboard-focusable.
`FileUploadInput`	`FileUploadInputProps`	`"input"`	Visually hidden native input element synchronized with selected files for form submission.
`FileUploadTrigger`	`FileUploadTriggerProps`	`"button"`	Accessible button element opening the native system file picker.
`FileUploadList`	`FileUploadListProps`	`"ul"`	List container supporting children or a render function. Set layout="tiles" for a horizontal attachment strip; defaults to rows.
`FileUploadItem`	`FileUploadItemProps`	`"li"`	Scopes file data and index for an item. Set layout="upload" for a compact upload card, or layout="tile" for compact attachments. Defaults to row.
`FileUploadItemPreview`	`FileUploadItemPreviewProps`	`Optional`	Shows a local image preview with object URL cleanup. Children provide the document or failed-image fallback.
`FileUploadItemName`	`FileUploadItemNameProps`	`"span"`	Displays the file name with automatic ellipsis truncation.
`FileUploadItemSize`	`FileUploadItemSizeProps`	`"span"`	Displays the formatted file size with tabular figures.
`FileUploadItemStatus`	`FileUploadItemStatusProps`	`"span"`	Renders and announces pending, uploading, success, or error states. Error status also marks the file card border.
`FileUploadItemProgress`	`FileUploadItemProgressProps`	`"div"`	Renders a standard progress bar inside each file card. Applications own transport and progress updates.
`FileUploadItemRemove`	`FileUploadItemRemoveProps`	`"button"`	Accessible button to remove a file from the list with focus restoration.

import { FileUpload, FileUploadDropzone, FileUploadInput, FileUploadItem, FileUploadItemName, FileUploadItemPreview, FileUploadItemProgress, FileUploadItemRemove, FileUploadItemSize, FileUploadItemStatus, FileUploadList, FileUploadTrigger, } from "@mizen-labs/ui";

Anatomy

The parts and how they nest, taken from the preview above.

<FileUpload>
	<FileUploadDropzone>
		<FileUploadTrigger />
	</FileUploadDropzone>
	<FileUploadInput />
	<FileUploadList>
		<FileUploadItem>
			<FileUploadItemPreview />
			<FileUploadItemName />
			<FileUploadItemSize />
			<FileUploadItemStatus />
			<FileUploadItemRemove />
			<FileUploadItemProgress />
		</FileUploadItem>
	</FileUploadList>
</FileUpload>

Guidance

Practice

Show accepted formats and size limits before selection. Keep rejection reasons and progress beside each file.

Guidance

Boundary

Scope

The application owns transport, cancellation, and retries. Validate file content and limits on the server.

API reference

Public props from @mizen-labs/ui. Use exported prop types for the complete TypeScript contract.

Prop	Type	Default	Description
`accept`	`string`	`—`	Accepted file types specifier string matching file extensions or MIME patterns.
`defaultValue`	`readonly File[]`	`[]`	Initial files array for uncontrolled file upload presentation.
`disabled`	`boolean`	`false`	Disables user interaction across picker trigger, dropzone, and remove actions.
`maxFiles`	`number`	`1`	Maximum number of files allowed in the upload collection.
`maxSize`	`number`	`—`	Maximum allowed file size in bytes for each uploaded file.
`name`	`string`	`—`	Field name submitted with form data on the synchronized native file input.
`value`	`readonly File[]`	`—`	Controlled array of files.
`onValueChange`	`(files: readonly File[], details: FileUploadChangeDetails) => void`	`—`	Callback fired when files are added, dropped, or removed with change details.
`onFileReject`	`(rejections: readonly FileRejection[]) => void`	`—`	Callback fired when files are rejected due to type, size, or count constraints.
`FileUpload`	`FileUploadProps`	`"div"`	Root container providing file upload context, drag-and-drop coordination, and accessibility announcements.
`FileUploadDropzone`	`FileUploadDropzoneProps`	`"div"`	Non-interactive drag-and-drop surface receiving files without pretending to be keyboard-focusable.
`FileUploadInput`	`FileUploadInputProps`	`"input"`	Visually hidden native input element synchronized with selected files for form submission.
`FileUploadTrigger`	`FileUploadTriggerProps`	`"button"`	Accessible button element opening the native system file picker.
`FileUploadList`	`FileUploadListProps`	`"ul"`	List container supporting children or a render function. Set layout="tiles" for a horizontal attachment strip; defaults to rows.
`FileUploadItem`	`FileUploadItemProps`	`"li"`	Scopes file data and index for an item. Set layout="upload" for a compact upload card, or layout="tile" for compact attachments. Defaults to row.
`FileUploadItemPreview`	`FileUploadItemPreviewProps`	`Optional`	Shows a local image preview with object URL cleanup. Children provide the document or failed-image fallback.
`FileUploadItemName`	`FileUploadItemNameProps`	`"span"`	Displays the file name with automatic ellipsis truncation.
`FileUploadItemSize`	`FileUploadItemSizeProps`	`"span"`	Displays the formatted file size with tabular figures.
`FileUploadItemStatus`	`FileUploadItemStatusProps`	`"span"`	Renders and announces pending, uploading, success, or error states. Error status also marks the file card border.
`FileUploadItemProgress`	`FileUploadItemProgressProps`	`"div"`	Renders a standard progress bar inside each file card. Applications own transport and progress updates.
`FileUploadItemRemove`	`FileUploadItemRemoveProps`	`"button"`	Accessible button to remove a file from the list with focus restoration.