Experience UI Bundle File Upload Generate

File Upload API (workflow)

When 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.

CRITICAL: This is an API-only package

The package exports programmatic APIs, not React components or hooks. You will:

• Use the upload() function to handle file uploads with progress tracking
• Build your own custom UI (file input, dropzone, progress bars, etc.)
• Track upload progress through the onProgress callback

Do NOT:

• Expect pre-built components like <FileUpload /> — they are not exported
• Try to import React hooks like useFileUpload — they are not exported
• Look for dropzone components — they are not exported

The source code contains reference components for demonstration, but they are not available as imports. Use them as examples to build your own UI.

1. Install the package

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)

2. Understand the three upload patterns

Pattern A: Basic upload (no record linking)

Upload files to Salesforce and get back contentBodyId for each file. No ContentVersion record is created.

When to use:

• User wants to upload files first, then create/link them to a record later
• Building a multi-step form where the record doesn't exist yet
• Deferred record linking scenarios

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)

Pattern B: Upload with immediate record linking

Upload files and immediately link them to an existing Salesforce record by creating ContentVersion records.

When to use:

• Record already exists (Account, Opportunity, Case, etc.)
• User wants files immediately attached to the record
• Direct upload-and-attach scenarios

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)

Pattern C: Deferred record linking (record creation flow)

Upload files without a record, then link them after the record is created.

When to use:

• Building a "create record with attachments" form
• Record doesn't exist until form submission
• Need to upload files before knowing the final record ID

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,
  );
}

3. Build your custom UI

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>
  );
}

4. Track upload progress

The onProgress callback fires multiple times for each file as it moves through stages:

Always provide visual feedback:

• Show file name
• Display current status
• Render progress bar for "uploading" status
• Show error message if status is "error"

5. Cancel uploads (optional)

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();
};

6. Link to current user (special case)

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 });

API Reference

upload(options)

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[]>

createContentVersion(file, contentBodyId, recordId)

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 upload
• recordId — Record ID for FirstPublishLocationId

Returns: ContentVersion ID if successful

getCurrentUserId()

Get the current user's Salesforce ID.