Examples
Controlled queue and retry
Manage each file status in the feature and show progress, error, and retry feedback without a service request.
Upload attachments
Feature state owns the controlled queue. These controls simulate progress and retry without a backend request.
Attachments
PDF, PNG, and JPEG files up to 5 MB each; the queue is controlled by this feature.
No files in the queue.
Controlled file upload queue with progress and retry states
"use client";
import { useRef, useState } from "react";
import { Button } from "@phuctech/ui/components/button";
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@phuctech/ui/components/card";
import { FileUpload } from "@phuctech/ui/components/file-upload";
import type { FileUploadItem } from "@phuctech/ui/components/file-upload";
export function Example() {
const [files, setFiles] = useState<FileUploadItem[]>([]);
const [notice, setNotice] = useState("");
const nextId = useRef(0);
const hasQueued = files.some((item) => (item.status ?? "queued") === "queued");
const hasUploading = files.some((item) => item.status === "uploading");
function addSampleFile() {
if (files.length >= 3) return;
nextId.current += 1;
const file = new File(["Fixture research summary."], `research-summary-${nextId.current}.pdf`, { type: "application/pdf" });
setFiles((current) => [...current, { id: `fixture-${nextId.current}`, file, status: "queued" }]);
setNotice("A sample PDF was added to the controlled queue.");
}
function markQueuedAsUploading() {
setFiles((current) => current.map((item) => (item.status ?? "queued") === "queued" ? { ...item, status: "uploading", progress: 45 } : item));
setNotice("Queued files are marked as uploading. No request was sent.");
}
function completeUploads() {
setFiles((current) => current.map((item) => item.status === "uploading" ? { ...item, status: "success", progress: 100 } : item));
setNotice("The local upload simulation is complete.");
}
function showRetryableFailure() {
const target = files.find((item) => (item.status ?? "queued") === "queued");
if (!target) return;
setFiles((current) => current.map((item) => item.id === target.id ? { ...item, status: "error", error: "The simulated transfer stopped. Retry to continue." } : item));
setNotice(`${target.file.name} is ready to retry.`);
}
function retry(item: FileUploadItem) {
setFiles((current) => current.map((queued) => queued.id === item.id ? { ...queued, status: "uploading", progress: 35, error: undefined } : queued));
setNotice(`Retry started for ${item.file.name}. Complete the local simulation when ready.`);
}
return (
<Card className="w-full max-w-3xl min-w-0">
<CardHeader><CardTitle>Upload attachments</CardTitle><CardDescription>Feature state owns the controlled queue. These controls simulate progress and retry without a backend request.</CardDescription></CardHeader>
<CardContent className="grid min-w-0 gap-4">
<div className="flex flex-wrap gap-2">
<Button type="button" variant="outline" onClick={addSampleFile} disabled={files.length >= 3}>Add sample PDF</Button>
<Button type="button" variant="outline" onClick={showRetryableFailure} disabled={!hasQueued}>Simulate failure</Button>
<Button type="button" onClick={markQueuedAsUploading} disabled={!hasQueued}>Start queued uploads</Button>
<Button type="button" variant="secondary" onClick={completeUploads} disabled={!hasUploading}>Complete uploads</Button>
</div>
{notice ? <p role="status" className="text-sm text-muted-foreground">{notice}</p> : null}
<FileUpload
label="Attachments"
description="PDF, PNG, and JPEG files up to 5 MB each; the queue is controlled by this feature."
accept=".pdf,image/png,image/jpeg"
maxFiles={3}
maxFileSizeBytes={5 * 1024 * 1024}
files={files}
onFilesChange={setFiles}
onRetry={retry}
onValidationError={(issues) => setNotice(`${issues.length} file${issues.length === 1 ? "" : "s"} did not meet the queue rules.`)}
/>
</CardContent>
</Card>
);
}
Controlled queue
The feature owns the ordered file list and supplies it to FileUpload. The component validates local accept and size rules, then emits proposed queue changes. The feature owns upload requests, status transitions, retry policy, cancellation, and persistence; this example uses fixture-only state.
States and retry
queued: keep the file name and size visible before upload begins.uploading: show per-file Progress and prevent duplicate work in the feature.success: report completion without leaving stale retry controls visible.error: explain the failed file and preserve its context; offer Retry only when the feature can safely resume.
Accessibility
- Name the queue and each remove/retry action with the affected file.
- Expose validation failures and transfer failures in text, not only with a color or progress change.
- Keep the file list in a bounded scroll region when it can grow; preserve the queue heading and controls.
- Announce state changes near the queue and do not move focus when a progress value updates.
Do and don’t
Keep files and statuses in feature state so retries and completion remain controlled and testable.
Assume that selecting a file uploads it, or put service-specific network behavior inside FileUpload.
The runnable source at src/components/design/examples/source/upload-flow-pattern.tsx simulates each transition locally and makes no request. The composition has no pattern-level property playground.
Related
- FileUpload owns the picker, queue presentation, and validation surface.
- Progress describes an active transfer.
- Alert presents actionable failures.