Skip to content

Design system

Documentation

DesignComponents / FileUpload

Components / FileUpload

Beta

FileUpload

Collect files into an application-owned queue with clear client-side limits and status.

On this page

Examples

Controlled file queue

The feature owns the queue; the component handles file selection and client-side limits.

Project documents

Add up to five PDF or Office documents.

No files in the queue.

Controlled project document queue

Client-side restrictions

Explain rejected file types and limits while keeping the rule in the feature configuration.

Reference material

Images and PDFs only, up to 5 MB each.

No files in the queue.

File type and size validation

Try the props

Adjust the queue limit and disabled state. No upload request is made.

Attachments

Select PDF files or drag them into this area.

No files in the queue.

FileUpload property playground

When to use

Use FileUpload when a feature needs file selection, drag and drop, a visible queue, client-side accept/size/count checks, and status supplied by the feature. The queue is controlled: pass files and update it in onFilesChange. FileUpload does not upload, retry requests, or delete remote files. Browser-side checks improve feedback but do not replace validation on the receiving server.

Usage

import { useState } from "react";
import { FileUpload, type FileUploadItem } from "@phuctech/ui/components/file-upload";

export function AttachmentsField() {
const [files, setFiles] = useState<FileUploadItem[]>([]);
return (
  <FileUpload
    files={files}
    onFilesChange={setFiles}
    accept="application/pdf,.doc,.docx"
    maxFiles={5}
    maxFileSizeBytes={10 * 1024 * 1024}
  />
);
}

The example callback name represents feature-owned behavior; FileUpload only notifies the feature. Each selected item begins in queued state. Pass updated status, progress, and error fields back through files as the upload feature advances.

API

Component API
PropTypeDefaultDescriptionConstraints
filesreadonly FileUploadItem[]requiredThe current controlled queue.Each item has a unique id and File; status, progress, and error are application-owned.
onFilesChange(files: FileUploadItem[]) => voidrequiredReceives a new queue after accepted files are added or an item is removed.The component never mutates the supplied queue.
FileUploadItem{ id, file, status?, progress?, error? }status=queuedDescribes one local file and its visible application status.status is queued, uploading, success, or error; progress is from 0 to 100 when known.
acceptstringall file typesApplies comma-separated MIME types, wildcards, and extensions.This is client-side feedback only; validate content and authorization on the server.
maxFiles / maxFileSizeBytesnumber / number5 / unlimitedLimits the total queue length and each file size.maxFileSizeBytes is measured in bytes; rejected files are reported through onValidationError.
multiplebooleantrueAllows selecting several files at once.When false, the queue limit is one file.
onValidationError(issues: FileUploadIssue[]) => void—Receives rejected files and their type, size, or max-files reason.The user also sees a visible validation message.
onRetry(item: FileUploadItem) => void—Requests a retry for a failed item.The feature starts the request and returns updated status/progress through files.
disabled / readOnlybooleanfalseBlocks queue changes or presents an inherited queue without actions.Existing file status remains visible.
label / descriptionstringAttachments / —Names the queue and explains supported input.Keep restrictions readable and do not rely only on the dropzone text.

Tokens

Component tokens
TokenRoleEffective valueUsage
--color-border-* / --color-bg-surfaceDrop area and queue rowsShared semantic surface rolesKeeps the drop target and file list legible in light and dark themes.
--color-danger-* / --color-success-*Validation and statusShared semantic feedback rolesPairs rejected files and upload outcomes with readable text.
--size-control-* / --size-icon-*Choose, retry, and remove controlsShared control scaleKeeps actions aligned with other form controls.

Accessibility

  • The upload surface has a visible label and description; file selection uses a keyboard-operable Button.
  • Rejected files are announced in an alert. Queue changes and empty state are readable without color alone.
  • Each remove action includes the file name. Progress is labeled with the file name; retry is shown as a text button.
  • Long queues scroll inside a bounded region while the label, choose button, and validation remain visible.

Do and don’t

Do

Validate content, permissions, and size again on the server that receives the file.

Don’t

Describe a file as uploaded until the feature confirms the remote operation succeeded.

  • Progress renders application-owned upload progress.
  • Alert explains rejected files and recovery.
  • Field provides shared form labeling and validation context.