Terminal
Terminal/Skill
Adds file upload to a React UI bundle app through a programmatic upload API with progress tracking and ContentVersion records.
By Salesforce
Works with
npx skills add forcedotcom/sf-skills --skill experience-ui-bundle-file-upload-generateWhen the user wants file upload functionality in a React UI bundle, follow this workflow. This feature provides APIs only — you must build the UI components yourself using the provided APIs.
The package exports programmatic APIs, not React components or hooks. You will:
upload() function to handle file uploads with progress trackingonProgress callbackDo NOT:
<FileUpload /> — they are not exporteduseFileUpload — they are not exportedThe source code contains reference components for demonstration, but they are not available as imports. Use them as examples to build your own UI.
npm install @salesforce/ui-bundle-template-feature-react-file-upload
Dependencies are automatically installed:
@salesforce/ui-bundle (API client)@salesforce/platform-sdk (data SDK; the old @salesforce/sdk-data name is dead — see the experience-ui-bundle-salesforce-data-access skill)Upload files to Salesforce and get back contentBodyId for each file. No ContentVersion record is created.
When to use:
import { upload } from "@salesforce/ui-bundle-template-feature-react-file-upload";
const results = await upload({
files: [file1, file2],
onProgress: (progress) => {
console.log(`${progress.fileName}: ${progress.status} - ${progress.progress}%`);
},
});
// results[0].contentBodyId: "069..." (always available)
// results[0].contentVersionId: undefined (no record linked)
Upload files and immediately link them to an existing Salesforce record by creating ContentVersion records.
When to use:
import { upload } from "@salesforce/ui-bundle-template-feature-react-file-upload";
const results = await upload({
files: [file1, file2],
recordId: "001xx000000yyyy", // Existing record ID
onProgress: (progress) => {
console.log(`${progress.fileName}: ${progress.status} - ${progress.progress}%`);
},
});
// results[0].contentBodyId: "069..." (always available)
// results[0].contentVersionId: "068..." (linked to record)
Upload files without a record, then link them after the record is created.
When to use:
import {
upload,
createContentVersion,
} from "@salesforce/ui-bundle-template-feature-react-file-upload";
// Step 1: Upload files (no recordId)
const uploadResults = await upload({
files: [file1, file2],
onProgress: (progress) => console.log(progress),
});
// Step 2: Create the record
const newRecordId = await createRecord(formData);
// Step 3: Link uploaded files to the new record
for (const file of uploadResults) {
const contentVersionId = await createContentVersion(
new File([""], file.fileName),
file.contentBodyId,
newRecordId,
);
}
The package provides the backend — you build the frontend. Here's a minimal example:
import {
upload,
type FileUploadProgress,
} from "@salesforce/ui-bundle-template-feature-react-file-upload";
import { useState } from "react";
function CustomFileUpload({ recordId }: { recordId?: string }) {
const [progress, setProgress] = useState<Map<string, FileUploadProgress>>(new Map());
const handleFileSelect = async (event: React.ChangeEvent<HTMLInputElement>) => {
const files = Array.from(event.target.files || []);
await upload({
files,
recordId,
onProgress: (fileProgress) => {
setProgress((prev) => new Map(prev).set(fileProgress.fileName, fileProgress));
},
});
};
return (
<div>
<input type="file" multiple onChange={handleFileSelect} />
{Array.from(progress.entries()).map(([fileName, fileProgress]) => (
<div key={fileName}>
{fileName}: {fileProgress.status} - {fileProgress.progress}%
{fileProgress.error && <span>Error: {fileProgress.error}</span>}
</div>
))}
</div>
);
}
The onProgress callback fires multiple times for each file as it moves through stages:
| Status | When | Progress Value |
|---|---|---|
"pending" | File queued for upload | 0 |
"uploading" | Upload in progress (XHR) | 0-100 (percentage) |
"processing" | Creating ContentVersion (if recordId provided) | 0 |
"success" | Upload complete | 100 |
"error" | Upload failed | 0 |
Always provide visual feedback:
Use an AbortController to allow users to cancel uploads:
const abortController = new AbortController();
const handleUpload = async (files: File[]) => {
try {
await upload({
files,
signal: abortController.signal,
onProgress: (progress) => console.log(progress),
});
} catch (error) {
console.error("Upload cancelled or failed:", error);
}
};
const cancelUpload = () => {
abortController.abort();
};
If the user wants to upload files to their own profile or personal library:
import {
upload,
getCurrentUserId,
} from "@salesforce/ui-bundle-template-feature-react-file-upload";
const userId = await getCurrentUserId();
await upload({ files, recordId: userId });
Main upload API that handles complete flow with progress tracking.
interface UploadOptions {
files: File[];
recordId?: string | null; // If provided, creates ContentVersion
onProgress?: (progress: FileUploadProgress) => void;
signal?: AbortSignal; // Optional cancellation
}
interface FileUploadProgress {
fileName: string;
status: "pending" | "uploading" | "processing" | "success" | "error";
progress: number; // 0-100 for uploading, 0 for other states
error?: string;
}
interface FileUploadResult {
fileName: string;
size: number;
contentBodyId: string; // Always available
contentVersionId?: string; // Only if recordId was provided
}
Returns: Promise<FileUploadResult[]>
Manually create a ContentVersion record from a previously uploaded file.
async function createContentVersion(
file: File,
contentBodyId: string,
recordId: string,
): Promise<string | undefined>;
Parameters:
file — File object (used for metadata like name)contentBodyId — ContentBody ID from previous uploadrecordId — Record ID for FirstPublishLocationIdReturns: ContentVersion ID if successful
Get the current user's Salesforce ID.
async function getCurrentUserId(): Promise<string>;
Returns: Current user ID
<input type="file" multiple accept=".pdf,.doc,.docx,.jpg,.png" onChange={handleFileSelect} />
Build your own dropzone using native events:
function DropZone({ onDrop }: { onDrop: (files: File[]) => void }) {
const handleDrop = (e: React.DragEvent) => {
e.preventDefault();
const files = Array.from(e.dataTransfer.files);
onDrop(files);
};
return (
<div
onDrop={handleDrop}
onDragOver={(e) => e.preventDefault()}
style={{ border: "2px dashed #ccc", padding: "2rem" }}
>
Drop files here
</div>
);
}
{
progress.status === "uploading" && (
<div style={{ width: "100%", background: "#eee" }}>
<div
style={{
width: `${progress.progress}%`,
background: "#0176d3",
height: "8px",
}}
/>
</div>
);
}
User asks for file upload functionality:
Ask about record context:
Based on response:
recordIdgetCurrentUserId()Build the UI:
Test the implementation:
contentBodyId is returnedrecordId was provided, verify contentVersionId is returnedThe package includes a reference implementation in src/features/fileupload/ with:
FileUpload.tsx — Complete component with dropzone and dialogFileUploadDialog.tsx — Progress tracking dialogFileUploadDropZone.tsx — Drag-and-drop zoneuseFileUpload.ts — React hook for state managementThese are NOT exported but can be viewed as examples. Read the source files to understand patterns for building your own UI.
Upload fails with CORS error:
localhostNo progress updates:
onProgress callback is providedContentVersion not created:
recordId is provided to upload() functionFiles upload but don't appear in record:
recordId is correctcontentVersionId in results)upload() API<FileUpload /> component — it's not exporteduseFileUpload hook — it's not exported