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
"use client";
import { useState } from "react";
import { FileUpload, type FileUploadItem } from "@phuctech/ui/components/file-upload";
export function Example() {
const [files, setFiles] = useState<FileUploadItem[]>([]);
return (
<FileUpload
label="Project documents"
description="Add up to five PDF or Office documents."
files={files}
onFilesChange={setFiles}
accept="application/pdf,.doc,.docx"
maxFiles={5}
maxFileSizeBytes={10 * 1024 * 1024}
/>
);
}
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
"use client";
import { useState } from "react";
import { FileUpload, type FileUploadItem } from "@phuctech/ui/components/file-upload";
export function Example() {
const [files, setFiles] = useState<FileUploadItem[]>([]);
return (
<FileUpload
label="Reference material"
description="Images and PDFs only, up to 5 MB each."
files={files}
onFilesChange={setFiles}
accept="image/*,application/pdf"
maxFiles={3}
maxFileSizeBytes={5 * 1024 * 1024}
/>
);
}
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
"use client";
import { useState } from "react";
import { FileUpload, type FileUploadItem } from "@phuctech/ui/components/file-upload";
export function Example({ maxFiles = 3, disabled = false }: { maxFiles?: number; disabled?: boolean }) {
const [files, setFiles] = useState<FileUploadItem[]>([]);
return (
<FileUpload
label="Attachments"
description="Select PDF files or drag them into this area."
files={files}
onFilesChange={setFiles}
accept=".pdf"
maxFiles={maxFiles}
maxFileSizeBytes={5 * 1024 * 1024}
disabled={disabled}
/>
);
}
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
Tokens
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
Validate content, permissions, and size again on the server that receives the file.
Describe a file as uploaded until the feature confirms the remote operation succeeded.