File Upload

A component that is used to upload multiple files, with ability to drag and drop files.

Import

ts
import { FileUpload } from "@kobalte/core/file-upload";
// or
import { Root } from "@kobalte/core/file-upload";
// or (deprecated)
import { FileUpload } from "@kobalte/core";

ts
import { FileUpload } from "@kobalte/core/file-upload";
// or
import { Root } from "@kobalte/core/file-upload";
// or (deprecated)
import { FileUpload } from "@kobalte/core";

Features

Supports uploading multiple files at once.
Supports drag and drop functionality for uploading files.
Supports maximum file limits to restrict the number of files that can be uploaded.
Supports file size validation to ensure that files are within the specified size limits.
Supports custom validation rules for uploaded files.
Supports restricting the types of files that can be uploaded (e.g., images, documents).
Displays a list of files that have been selected for upload.
Allows users to remove files from the upload list before uploading.
Provides a preview of image files before they are uploaded.
Displays the size of each file in the upload list.
Supports customizing the components with custom styles and classes.

Anatomy

The File Upload consists of:

FileUpload: The root container for the File Upload component.
FileUpload.Dropzone: The dropzone area where files can be dragged and dropped.
FileUpload.Trigger: The trigger element that opens the file selection dialog.
FileUpload.Label: The label for the File Upload component to toggle the file selection dialog.
FileUpload.HiddenInput: The hidden input element that triggers the file selection dialog.
FileUpload.ItemGroup: The container for the list of files that have been selected for upload.
FileUpload.Item: The individual file item in the list of files that have been selected for upload.
FileUpload.Preview: The preview container for image files that have been selected for upload.
FileUpload.ItemPreviewImage: The preview image for image files that have been selected for upload.
FileUpload.ItemName: The name of the file that has been selected for upload.
FileUpload.ItemSize: The size of the file that has been selected for upload.
FileUpload.ItemDeleteTrigger: The trigger element to remove a file from the list of files that have been selected for upload.
FileUpload.Context: The context provider for the File Upload component.

tsx
<FileUpload>
	<FileUpload.Label></FileUpload.Label>
	<FileUpload.DropZone>
		<FileUpload.Trigger></FileUpload.Trigger>
	</FileUpload.DropZone>
	<FileUpload.HiddenInput />
	<FileUpload.ItemGroup>
		<FileUpload.Context>
			<FileUpload.Item>
				<FileUpload.ItemPreview>
					<FileUpload.ItemPreviewImage />
				</FileUpload.ItemPreview>
				<FileUpload.ItemSize />
				<FileUpload.ItemName />
				<FileUpload.ItemDeleteTrigger />
			</FileUpload.Item>
		</FileUpload.Context>
	</FileUpload.ItemGroup>
</FileUpload>

tsx
<FileUpload>
	<FileUpload.Label></FileUpload.Label>
	<FileUpload.DropZone>
		<FileUpload.Trigger></FileUpload.Trigger>
	</FileUpload.DropZone>
	<FileUpload.HiddenInput />
	<FileUpload.ItemGroup>
		<FileUpload.Context>
			<FileUpload.Item>
				<FileUpload.ItemPreview>
					<FileUpload.ItemPreviewImage />
				</FileUpload.ItemPreview>
				<FileUpload.ItemSize />
				<FileUpload.ItemName />
				<FileUpload.ItemDeleteTrigger />
			</FileUpload.Item>
		</FileUpload.Context>
	</FileUpload.ItemGroup>
</FileUpload>

Example

File Upload

Drop your files here...

Usage

HTML forms

By passing name prop to FileUpload.HiddenInput, you can use FileUpload in HTML forms.

tsx
function HTMLFormExample() {
	let formRef: HTMLFormElement | undefined;
	const onSubmit = (e: SubmitEvent) => {
		// handle form submission.
		const formData = new FormData(formRef);
		const uploadedFiles = formData.getAll("uploaded-files");
	};
	return (
		<form ref={formRef} onSubmit={onSubmit}>
			<FileUpload
				multiple
				maxFiles={5}
				onFileAccept={data => console.log("data", data)}
				onFileReject={data => console.log("data", data)}
				onFileChange={data => console.log("data", data)}
			>
				<FileUpload.Label>File Upload</FileUpload.Label>
				<FileUpload.DropZone>
					Drop your files here...
					<FileUpload.Trigger>Choose files!</FileUpload.Trigger>
				</FileUpload.DropZone>
				<FileUpload.HiddenInput name="uploaded-files" />
				<FileUpload.ItemGroup>
					<FileUpload.Context>
						{context => {
							return (
								<For each={context.acceptedFiles}>
									{file => (
										<FileUpload.Item file={file}>
											<FileUpload.ItemPreview type="image/*" class={"fileUpload__itemPreview"}>
												<FileUpload.ItemPreviewImage class={"fileUpload__itemPreviewImage"} />
											</FileUpload.ItemPreview>
											<FileUpload.ItemName />
											<FileUpload.ItemSize />
											<FileUpload.ItemDeleteTrigger>Delete</FileUpload.ItemDeleteTrigger>
										</FileUpload.Item>
									)}
								</For>
							);
						}}
					</FileUpload.Context>
				</FileUpload.ItemGroup>
			</FileUpload>
			<div>
				<button type="reset">Reset</button>
				<button type="submit">Submit</button>
			</div>
		</form>
	);
}

tsx
function HTMLFormExample() {
	let formRef: HTMLFormElement | undefined;
	const onSubmit = (e: SubmitEvent) => {
		// handle form submission.
		const formData = new FormData(formRef);
		const uploadedFiles = formData.getAll("uploaded-files");
	};
	return (
		<form ref={formRef} onSubmit={onSubmit}>
			<FileUpload
				multiple
				maxFiles={5}
				onFileAccept={data => console.log("data", data)}
				onFileReject={data => console.log("data", data)}
				onFileChange={data => console.log("data", data)}
			>
				<FileUpload.Label>File Upload</FileUpload.Label>
				<FileUpload.DropZone>
					Drop your files here...
					<FileUpload.Trigger>Choose files!</FileUpload.Trigger>
				</FileUpload.DropZone>
				<FileUpload.HiddenInput name="uploaded-files" />
				<FileUpload.ItemGroup>
					<FileUpload.Context>
						{context => {
							return (
								<For each={context.acceptedFiles}>
									{file => (
										<FileUpload.Item file={file}>
											<FileUpload.ItemPreview type="image/*" class={"fileUpload__itemPreview"}>
												<FileUpload.ItemPreviewImage class={"fileUpload__itemPreviewImage"} />
											</FileUpload.ItemPreview>
											<FileUpload.ItemName />
											<FileUpload.ItemSize />
											<FileUpload.ItemDeleteTrigger>Delete</FileUpload.ItemDeleteTrigger>
										</FileUpload.Item>
									)}
								</For>
							);
						}}
					</FileUpload.Context>
				</FileUpload.ItemGroup>
			</FileUpload>
			<div>
				<button type="reset">Reset</button>
				<button type="submit">Submit</button>
			</div>
		</form>
	);
}

API Reference

FileUpload

FileUpload is equivalent to the Root import from @kobalte/core/file-upload (and deprecated FileUpload.Root).

Prop	Description
`multiple`	`boolean` Allows multiple files to be uploaded
`maxFiles`	`number` The maximum number of files that can be uploaded
`disabled`	`boolean` Disables the file upload component
`accept`	`string \| string[] \| undefined` The types of files that can be uploaded.
`allowDragAndDrop`	`boolean` Allows files to be dragged and dropped into the component.
`maxFileSize`	`number` The maximum size of the file that can be uploaded in bytes.
`minFileSize`	`number` The minimum size of the file that can be uploaded in bytes.
`onFileAccept`	`(files: File[]) => void` Callback function that is called when file(s) is(are) accepted.
`onFileReject`	`(files: FileRejection[]) => void` Callback function that is called when a file(s) is(are) rejected.
`onFileChange`	`(details: Details) => void` Callback function that is called when the list of files changes.
`validateFile`	`(file: File) => FileError[] \| null` Custom validation function for files.

FileUpload.Item

Prop	Description
`file`	`File` Selected file object

FileUpload.ItemSize

Prop	Description
`precision`	`number` The number of decimal places to round the file size to.

FileUpload.ItemPreview

Prop	Description
`type`	`string` The type of file to preview, only applicable for Images.

Accessibility

Keyboard Interactions

Key	Description
`Space`	When focus is on dropzone, opens the file dialog. When focus is on trigger, opens the file dialog.
`Enter`	When focus is on dropzone, opens the file dialog. When focus is on trigger, opens the file dialog.