@salesforce/webapp-template-feature-react-file-upload-experimental 1.60.0 → 1.60.2

package/README.md

@@ -2,6 +2,26 @@
 
 File upload feature: use the **FileUpload** component as-is with out-of-the-box UI, or build a **custom UI** with the `useFileUpload` hook (custom trigger, drop zone, or both).
 
+## Exports
+
+### Components & Hooks
+
+- **FileUpload** – Component with OOTB drop zone, dialog, and progress. Props: `accept?`, `multiple?`, `recordId?`, `onUploadComplete?`, `onUploadError?`, `className?`, `dropZoneClassName?`, `formatHint?`, `maxFileSize?`.
+- **useFileUpload** – Headless hook for custom UIs. Returns `getInputProps`, `openFilePicker`, `fileItems`, `getDropZoneProps`, `cancelFile`, `reset`, etc.
+- **UseFileUploadOptions** – Type for the `useFileUpload` options.
+
+### API Functions
+
+- **createContentVersion** – Manually create a ContentVersion record from a contentBodyId.
+
+### FileUpload component Props
+
+- **`recordId`** (optional): When provided, creates ContentVersion and links to this record. When omitted, only uploads file and returns `contentBodyId` without creating ContentVersion.
+- **`maxFileSize`** (optional): Maximum file size in MB. Files exceeding this limit are rejected. Default: 2 GB.
+- **`dropZoneClassName`** (optional): CSS classes for the drop zone (e.g., `"h-full"` for flex layouts).
+- **`formatHint`** (optional): Text hint shown in drop zone (e.g., "JPEG, PNG, PDF, up to 50MB").
+- **`onUploadComplete`**: Receives array of uploaded files with `name`, `size`, `contentBodyId`, and `contentVersionId` (if ContentVersion was created).
+
 ## Usage
 
 ### Option 1: FileUpload component (OOTB UI)
@@ -14,11 +34,62 @@ import { FileUpload } from "@salesforce/webapp-template-feature-react-file-uploa
 <FileUpload
   multiple
   accept="image/*,.pdf"
-  onUploadComplete={(files) => console.log("Uploaded:", files)}
+  recordId={accountId} // Creates ContentVersion and links to this record
+  maxFileSize={50} // 50 MB limit
+  formatHint="JPEG, PNG, PDF, up to 50MB"
+  onUploadComplete={(files) => {
+    // files[0].contentBodyId: "069..."
+    // files[0].contentVersionId: "068..."
+    console.log("Uploaded:", files);
+  }}
 />;
 ```
 
-### Option 2: Custom UI with your own trigger
+### Option 2: Upload file only (no ContentVersion)
+
+Omit `recordId` to only upload the file and get the `contentBodyId`:
+
+```tsx
+<FileUpload
+  multiple
+  onUploadComplete={(files) => {
+    // Only contentBodyId is returned, no ContentVersion created
+    console.log("Content Body ID:", files[0].contentBodyId);
+    console.log("Content Version ID:", files[0].contentVersionId); // undefined
+  }}
+/>
+```
+
+### Option 3: Manual ContentVersion creation
+
+Upload file first, then manually create ContentVersion:
+
+```tsx
+import {
+  FileUpload,
+  createContentVersion,
+  getCurrentUserId,
+} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+
+function MyComponent() {
+  const handleComplete = async (files) => {
+    const userId = await getCurrentUserId();
+
+    for (const file of files) {
+      const contentVersionId = await createContentVersion(
+        new File([""], file.name),
+        file.contentBodyId,
+        userId,
+      );
+      console.log("Created ContentVersion:", contentVersionId);
+    }
+  };
+
+  return <FileUpload onUploadComplete={handleComplete} />;
+}
+```
+
+### Option 4: Custom UI with your own trigger
 
 Use the `useFileUpload` hook to control when the file picker opens. Render a hidden input and your own button or action.
 
@@ -31,6 +102,7 @@ import {
 function CustomUploadButton() {
   const { getInputProps, openFilePicker } = useFileUpload({
     multiple: true,
+    maxFileSize: 50, // 50 MB limit
     onUploadComplete: (files) => console.log("Uploaded:", files),
   });
 
@@ -45,7 +117,7 @@ function CustomUploadButton() {
 }
 ```
 
-### Option 3: Custom UI with drop zone and progress
+### Option 5: Custom UI with drop zone and progress
 
 Build a custom drop zone and inline progress list (no dialog) using `getDropZoneProps` and `fileItems`:
 
@@ -55,6 +127,8 @@ import { useFileUpload } from "@salesforce/webapp-template-feature-react-file-up
 function MyUpload() {
   const { fileItems, getInputProps, getDropZoneProps, reset } = useFileUpload({
     multiple: true,
+    recordId: accountId,
+    maxFileSize: 100, // 100 MB limit
     onUploadComplete: (files) => console.log("Uploaded files:", files),
   });
 
@@ -77,17 +151,29 @@ function MyUpload() {
 }
 ```
 
-## Exports
+## API Reference
 
-- **FileUpload** – Component with OOTB drop zone, dialog, and progress. Props: `accept?`, `multiple?`, `recordId?`, `onUploadComplete?`, `onUploadError?`, `className?`.
-- **useFileUpload** – Headless hook for custom UIs. Returns `getInputProps`, `openFilePicker`, `fileItems`, `getDropZoneProps`, `cancelFile`, `reset`, etc.
-- **UseFileUploadOptions** – Type for the `useFileUpload` options.
+### createContentVersion(file, contentBodyId, recordId)
+
+Manually create a ContentVersion record from a previously uploaded file.
+
+**Parameters:**
+
+- `file` (File): The file object (used for metadata like name)
+- `contentBodyId` (string): The ContentBody ID from a previous upload
+- `recordId` (string): The record ID for FirstPublishLocationId (ex: Salesforce record id to attach file)
+
+**Returns:** `Promise<string | undefined>` - The ContentVersion ID if successful
+
+```tsx
+const contentVersionId = await createContentVersion(file, "069xx000000xxxx", "005xx000000yyyy");
+```
 
 ## Dependencies
 
 This feature depends on:
 
-- **feature-react-shadcn** – For UI components (Button, Dialog, etc.)
+- **@salesforce/webapp-template-feature-react-shadcn-experimental** – For UI components (Button, Dialog, etc.)
 - **@salesforce/webapp-experimental** – For API client and Salesforce integration
 
 ## Build & Testing
@@ -95,8 +181,8 @@ This feature depends on:
 You can test the extension of the base app and the components via the following:
 
 ```bash
-npm run build
-npm run start
+npx nx build
+npx nx start
 ```
 
-Open the app and use the Home page to test the FileUpload component.
+Open the app and navigate to the **Upload Test** page to test the FileUpload component with manual ContentVersion creation.

package/dist/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.60.2](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.60.1...v1.60.2) (2026-02-27)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
+## [1.60.1](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.60.0...v1.60.1) (2026-02-27)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
 # [1.60.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.59.2...v1.60.0) (2026-02-27)
 
 **Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental

package/dist/force-app/main/default/webapplications/feature-react-file-upload/package-lock.json

@@ -6071,19 +6071,19 @@
       }
     },
     "node_modules/@salesforce/sdk-core": {
-      "version": "1.59.2",
-      "resolved": "https://registry.npmjs.org/@salesforce/sdk-core/-/sdk-core-1.59.2.tgz",
-      "integrity": "sha512-s/7yAygrhMIoedsOm6/9af1Hu6W6Hnfm9E+RBMJ/wwTS8CXJ/Tuqrqod6FTawULqiTJbFhmeeQCjcf8q1pcKZg==",
+      "version": "1.60.1",
+      "resolved": "https://registry.npmjs.org/@salesforce/sdk-core/-/sdk-core-1.60.1.tgz",
+      "integrity": "sha512-o0S83oNDkiRgymXQvThBBk8VPTY8PbBYkAlCHyhebdMCirv5ADUIndJA/wtadSp2JhvkGidU2MDTucKOuf922w==",
       "license": "SEE LICENSE IN LICENSE.txt"
     },
     "node_modules/@salesforce/sdk-data": {
-      "version": "1.59.2",
-      "resolved": "https://registry.npmjs.org/@salesforce/sdk-data/-/sdk-data-1.59.2.tgz",
-      "integrity": "sha512-3jltn3XRYqHMTfY/X6T5vUY5NVGPAjfzM6+irLr+ih0eYWPsuO3d3iexd6ovgtQZ9Qmnl9ljG9TGoh+dappDFA==",
+      "version": "1.60.1",
+      "resolved": "https://registry.npmjs.org/@salesforce/sdk-data/-/sdk-data-1.60.1.tgz",
+      "integrity": "sha512-tNrmKi8xGUxLhM33PwhUzC/8/1fay699ERCkMHoMBYV211nowzFQGUHMFuLU8sjIfErm8QdCqzNMJ6spxno/dQ==",
       "license": "SEE LICENSE IN LICENSE.txt",
       "dependencies": {
         "@conduit-client/salesforce-lightning-service-worker": "^3.7.0",
-        "@salesforce/sdk-core": "^1.59.2"
+        "@salesforce/sdk-core": "^1.60.1"
       }
     },
     "node_modules/@salesforce/ts-types": {
@@ -6096,15 +6096,15 @@
       }
     },
     "node_modules/@salesforce/vite-plugin-webapp-experimental": {
-      "version": "1.59.2",
-      "resolved": "https://registry.npmjs.org/@salesforce/vite-plugin-webapp-experimental/-/vite-plugin-webapp-experimental-1.59.2.tgz",
-      "integrity": "sha512-xRngJFgVlPXcBoImpdPH8+rObCk4r4nH8jkVHP85pcooBAhqRVIl0nYusuQSL+L1jlbfLptPOBBjtTkuouwanQ==",
+      "version": "1.60.1",
+      "resolved": "https://registry.npmjs.org/@salesforce/vite-plugin-webapp-experimental/-/vite-plugin-webapp-experimental-1.60.1.tgz",
+      "integrity": "sha512-5hTBd6xmaTkgfmY1PGFuJqXvCuMTPiKeBqYNkKKl6me8uUWBUQ3s5blPCwvLZqz7quNRU+iqzZNz4Ccn7zZnhQ==",
       "dev": true,
       "license": "SEE LICENSE IN LICENSE.txt",
       "dependencies": {
         "@babel/core": "^7.28.4",
         "@babel/helper-plugin-utils": "^7.28.3",
-        "@salesforce/webapp-experimental": "^1.59.2"
+        "@salesforce/webapp-experimental": "^1.60.1"
       },
       "engines": {
         "node": ">=20.0.0"
@@ -6114,13 +6114,13 @@
       }
     },
     "node_modules/@salesforce/webapp-experimental": {
-      "version": "1.59.2",
-      "resolved": "https://registry.npmjs.org/@salesforce/webapp-experimental/-/webapp-experimental-1.59.2.tgz",
-      "integrity": "sha512-TOZEI7pQV+j3VE/o5V5UkKUoOo7JRXI1i4C5VmxSHcSUVUd/GSzQYZptf9704Vxbjjsw9uZSM7tPOHTWYfVD9g==",
+      "version": "1.60.1",
+      "resolved": "https://registry.npmjs.org/@salesforce/webapp-experimental/-/webapp-experimental-1.60.1.tgz",
+      "integrity": "sha512-RLu1w4pJQKyLfaGM/kv16BVfmG4m2/ICzRthynthxoIC2O51p0404ihi0sJ2mmOb/bwKCgH3HI9w9IGlU6LuBA==",
       "license": "SEE LICENSE IN LICENSE.txt",
       "dependencies": {
         "@salesforce/core": "^8.23.4",
-        "@salesforce/sdk-data": "^1.59.2",
+        "@salesforce/sdk-data": "^1.60.1",
         "axios": "^1.7.7",
         "micromatch": "^4.0.8",
         "path-to-regexp": "^8.3.0"

package/dist/force-app/main/default/webapplications/feature-react-file-upload/src/api/fileUpload.ts

@@ -3,16 +3,8 @@
  */
 
 import { createRecord, getCurrentUser } from "@salesforce/webapp-experimental/api";
-import { createDataSDK, type DataSDK } from "@salesforce/sdk-data";
 
-// Lazy-initialized SDK instance
-let sdkInstance: DataSDK | null = null;
-async function getSDK() {
-	if (!sdkInstance) {
-		sdkInstance = await createDataSDK();
-	}
-	return sdkInstance;
-}
+import { getDataSDK } from "@salesforce/sdk-data";
 
 declare const __SF_API_VERSION__: string;
 
@@ -25,7 +17,7 @@ export interface UploadConfig {
  * Get upload config (token, uploadUrl) from /connect/file/upload/config.
  */
 export async function getUploadConfig(): Promise<UploadConfig> {
-	const sdk = await getSDK();
+	const sdk = await getDataSDK();
 	if (!sdk?.fetch) {
 		throw new Error("Failed to initialize SDK");
 	}
@@ -120,10 +112,10 @@ function parseJsonResponse(text: string): Record<string, unknown> {
 export async function createContentVersion(
 	file: File,
 	contentBodyId: string,
-	userId: string,
+	recordId: string,
 ): Promise<string | undefined> {
 	const fields = {
-		FirstPublishLocationId: userId,
+		FirstPublishLocationId: recordId,
 		Title: fileNameWithoutExtension(file.name),
 		PathOnClient: file.name,
 		ContentBodyId: contentBodyId,

package/dist/force-app/main/default/webapplications/feature-react-file-upload/src/components/FileUpload.tsx

@@ -9,13 +9,21 @@ export interface FileUploadProps {
 	accept?: string;
 	/** Whether to allow multiple file selection. Default: false */
 	multiple?: boolean;
-	/** Record Id for FirstPublishLocationId (e.g. Account, Opportunity). When provided, files are linked to this record. Otherwise, current user Id is used. */
+	/** Record Id for FirstPublishLocationId (e.g. Account, Opportunity). When provided, files are linked to this record and ContentVersion is created. When null/undefined, only uploads file and returns contentBodyId without creating ContentVersion. */
 	recordId?: string;
-	/** Called when uploads complete. Receives array of successfully uploaded files with name, size, and contentVersionId. */
-	onUploadComplete?: (files: { name: string; size: number; contentVersionId?: string }[]) => void;
+	/** Called when uploads complete. Receives array of successfully uploaded files with name, size, contentBodyId, and contentVersionId (if ContentVersion was created). */
+	onUploadComplete?: (
+		files: { name: string; size: number; contentBodyId: string; contentVersionId?: string }[],
+	) => void;
 	onUploadError?: (file: File, error: string) => void;
 	/** Optional CSS class for the wrapper div */
 	className?: string;
+	/** Optional CSS class for the drop zone (e.g. "h-full" for flex layouts) */
+	dropZoneClassName?: string;
+	/** Optional format hint for drop zone (e.g. "JPEG, PNG, PDF, and MP4 formats, up to 50MB") */
+	formatHint?: string;
+	/** Maximum file size in MB. Files exceeding this limit are rejected with an error. Omit for default (2 GB). */
+	maxFileSize?: number;
 }
 
 /**
@@ -30,6 +38,9 @@ export function FileUpload({
 	onUploadComplete,
 	onUploadError,
 	className = "",
+	dropZoneClassName = "",
+	formatHint,
+	maxFileSize,
 }: FileUploadProps) {
 	const { fileItems, getInputProps, getDropZoneProps, isDragging, reset, cancelFile, allDone } =
 		useFileUpload({
@@ -38,6 +49,7 @@ export function FileUpload({
 			recordId,
 			onUploadComplete,
 			onUploadError,
+			maxFileSize,
 		});
 
 	const { dialogOpen, uploadedFileNames, handleOpenChange } = useFileUploadDialog({
@@ -45,6 +57,9 @@ export function FileUpload({
 		reset,
 	});
 
+	const effectiveFormatHint =
+		formatHint ?? (maxFileSize != null ? `Up to ${maxFileSize}MB` : undefined);
+
 	const inputProps = getInputProps();
 	const dropZoneProps = getDropZoneProps();
 
@@ -55,6 +70,8 @@ export function FileUpload({
 					inputProps={inputProps}
 					dropZoneProps={dropZoneProps}
 					isDragging={isDragging}
+					formatHint={effectiveFormatHint}
+					className={dropZoneClassName}
 				/>
 
 				<FileUploadDialog

package/dist/force-app/main/default/webapplications/feature-react-file-upload/src/components/FileUploadDialog.tsx

@@ -1,12 +1,12 @@
+import { Button } from "./ui/button";
 import {
-	Button,
 	Dialog,
 	DialogClose,
 	DialogContent,
 	DialogFooter,
 	DialogHeader,
 	DialogTitle,
-} from "@/components/ui";
+} from "./ui/dialog";
 import { FileUploadFileItem } from "./FileUploadFileItem";
 import { formatUploadSummary } from "../utils/fileUploadUtils";
 import { LABELS } from "../utils/labels";

package/dist/force-app/main/default/webapplications/feature-react-file-upload/src/components/FileUploadDropZone.tsx

@@ -1,6 +1,7 @@
-import { UtilityIcon } from "./FileUploadIcons";
 import { LABELS } from "../utils/labels";
 
+import { UtilityIcon } from "./FileUploadIcons";
+
 export interface FileUploadDropZoneProps {
 	/** Props for the hidden file input (ref, type, accept, multiple, onChange) */
 	inputProps: {
@@ -20,63 +21,70 @@ export interface FileUploadDropZoneProps {
 	};
 	/** Whether the user is currently dragging over the drop zone */
 	isDragging: boolean;
+	/** Optional format hint (e.g. "JPEG, PNG, PDF, and MP4 formats, up to 50MB"). Defaults to LABELS.formatHint. */
+	formatHint?: string;
+	/** Optional CSS class for the drop zone (e.g. "h-full" for flex layouts) */
+	className?: string;
 }
 
 const DROP_ZONE_BASE_CLASSES =
-	"mb-2 flex cursor-pointer flex-wrap items-center gap-3 rounded-[4px] border border-dashed p-1 transition-colors";
+	"mb-2 flex cursor-pointer flex-col items-center justify-center gap-2 rounded-lg border-2 border-dashed bg-white px-6 pt-4 pb-8 transition-colors";
 const DROP_ZONE_DRAGGING_CLASSES = "border-blue-500 bg-blue-50";
-const DROP_ZONE_IDLE_CLASSES = "hover:bg-gray-50";
-const BORDER_COLOR_IDLE = "rgb(116, 116, 116)";
+const DROP_ZONE_IDLE_CLASSES = "border-gray-300 hover:border-gray-400 hover:bg-gray-50";
 
 /**
- * Drop zone for file selection. Renders a dashed border area with "Upload Files"
- * button and "Or drop files" / "Drop files here" text. Accepts click and drag-and-drop.
+ * Drop zone for file selection. Renders a dashed border area with document icon,
+ * primary instruction text, and format hint. Accepts click and drag-and-drop.
  * Uses a hidden file input; props come from useFileUpload.
  */
 export function FileUploadDropZone({
 	inputProps,
 	dropZoneProps,
 	isDragging,
+	formatHint = LABELS.formatHint,
+	className = "",
 }: FileUploadDropZoneProps) {
 	const dropZoneClassName = [
 		DROP_ZONE_BASE_CLASSES,
 		isDragging ? DROP_ZONE_DRAGGING_CLASSES : DROP_ZONE_IDLE_CLASSES,
-	].join(" ");
+		className,
+	]
+		.filter(Boolean)
+		.join(" ");
 
 	return (
-		<>
-			<p className="mb-1 text-sm font-semibold text-gray-900">{LABELS.attach}</p>
-			<div
-				role="button"
-				tabIndex={0}
-				onClick={dropZoneProps.onClick}
-				onDragOver={dropZoneProps.onDragOver}
-				onDragLeave={dropZoneProps.onDragLeave}
-				onDrop={dropZoneProps.onDrop}
-				onKeyDown={dropZoneProps.onKeyDown}
-				className={dropZoneClassName}
-				style={!isDragging ? { borderColor: BORDER_COLOR_IDLE } : undefined}
-				aria-label={LABELS.dropZone}
-				data-testid="file-upload-drop-zone"
+		<div
+			role="button"
+			tabIndex={0}
+			onClick={dropZoneProps.onClick}
+			onDragOver={dropZoneProps.onDragOver}
+			onDragLeave={dropZoneProps.onDragLeave}
+			onDrop={dropZoneProps.onDrop}
+			onKeyDown={dropZoneProps.onKeyDown}
+			className={dropZoneClassName}
+			aria-label={LABELS.dropZone}
+			data-testid="file-upload-drop-zone"
+		>
+			<input
+				id="file-upload-input-id"
+				ref={inputProps.ref}
+				type="file"
+				accept={inputProps.accept}
+				multiple={inputProps.multiple}
+				onChange={inputProps.onChange}
+				className="sr-only"
+				aria-hidden
+			/>
+			<span
+				className="inline-flex h-12 w-12 shrink-0 items-center justify-center text-gray-500"
+				aria-hidden
 			>
-				<input
-					id="file-upload-input-id"
-					ref={inputProps.ref}
-					type="file"
-					accept={inputProps.accept}
-					multiple={inputProps.multiple}
-					onChange={inputProps.onChange}
-					className="sr-only"
-					aria-hidden
-				/>
-				<span className="inline-flex items-center gap-2 rounded-[4px] border border-gray-300 bg-white px-4 py-2 text-sm font-medium text-blue-600 hover:bg-gray-50">
-					<UtilityIcon id="upload" size="sm" />
-					{LABELS.uploadFiles}
-				</span>
-				<span className="text-sm text-gray-900">
-					{isDragging ? LABELS.dropFilesHere : LABELS.orDropFiles}
-				</span>
-			</div>
-		</>
+				<UtilityIcon id="image" />
+			</span>
+			<p className="text-center text-sm font-medium text-gray-900">
+				{isDragging ? LABELS.dropFilesHere : LABELS.chooseFileOrDrop}
+			</p>
+			<p className="text-center text-xs text-gray-500">{formatHint}</p>
+		</div>
 	);
 }

package/dist/force-app/main/default/webapplications/feature-react-file-upload/src/components/FileUploadFileItem.tsx

@@ -1,4 +1,4 @@
-import { Button } from "@/components/ui";
+import { Button } from "./ui/button";
 import { FileTypeIcon, UtilityIcon } from "./FileUploadIcons";
 import {
 	formatFileSize,

package/dist/force-app/main/default/webapplications/feature-react-file-upload/src/components/FileUploadIcons.tsx

@@ -1,6 +1,6 @@
-import symbolsUrl from "@assets/symbols.svg?url";
+import symbolsUrl from "../assets/symbols.svg?url";
 
-import utilitySvg from "@assets/utility.svg?url";
+import utilitySvg from "../assets/utility.svg?url";
 
 const IMAGE_EXTENSIONS = new Set([
 	"jpg",

package/dist/force-app/main/default/webapplications/feature-react-file-upload/src/hooks/useFileUpload.ts

@@ -13,14 +13,14 @@
  */
 import * as React from "react";
 import { flushSync } from "react-dom";
-import {
-	getUploadConfig,
-	uploadToUrl,
-	createContentVersion,
-	getCurrentUserId,
-} from "../api/fileUpload";
+import { getUploadConfig, uploadToUrl, createContentVersion } from "../api/fileUpload";
 import type { FileUploadItem, UploadedFile, UploadState } from "../types/fileUpload";
-import { isFileTooLarge, MAX_FILE_SIZE_BYTES, formatFileSize } from "../utils/fileUploadUtils";
+import {
+	isFileTooLarge,
+	MAX_FILE_SIZE_BYTES,
+	bytesFromMB,
+	formatFileSize,
+} from "../utils/fileUploadUtils";
 import { LABELS } from "../utils/labels";
 
 export interface UseFileUploadOptions {
@@ -28,12 +28,14 @@ export interface UseFileUploadOptions {
 	accept?: string;
 	/** Whether to allow multiple file selection. Default: false */
 	multiple?: boolean;
-	/** Record Id for FirstPublishLocationId (e.g. Account, Opportunity). When provided, files are linked to this record. Otherwise, current user Id is used. */
+	/** Record Id for FirstPublishLocationId (e.g. Account, Opportunity). When provided, files are linked to this record and ContentVersion is created. When null/undefined, only uploads file and returns contentBodyId without creating ContentVersion. */
 	recordId?: string;
-	/** Called when uploads complete. Receives array of successfully uploaded files with name, size, and contentVersionId. */
+	/** Called when uploads complete. Receives array of successfully uploaded files with name, size, contentBodyId, and contentVersionId (if ContentVersion was created). */
 	onUploadComplete?: (files: UploadedFile[]) => void;
 	/** Called when an upload fails. Receives the file and error message. */
 	onUploadError?: (file: File, error: string) => void;
+	/** Maximum file size in MB. Files exceeding this limit are rejected with an error. Omit for default (2 GB). */
+	maxFileSize?: number;
 }
 
 function updateItem(
@@ -69,7 +71,16 @@ interface UseFileUploadReturn {
 }
 
 export function useFileUpload(options: UseFileUploadOptions = {}): UseFileUploadReturn {
-	const { accept, multiple = false, recordId, onUploadComplete, onUploadError } = options;
+	const {
+		accept,
+		multiple = false,
+		recordId,
+		onUploadComplete,
+		onUploadError,
+		maxFileSize,
+	} = options;
+
+	const maxBytes = maxFileSize != null ? bytesFromMB(maxFileSize) : MAX_FILE_SIZE_BYTES;
 
 	const [fileItems, setFileItems] = React.useState<FileUploadItem[]>([]);
 	const [isDragging, setIsDragging] = React.useState(false);
@@ -96,11 +107,11 @@ export function useFileUpload(options: UseFileUploadOptions = {}): UseFileUpload
 			const files = e.target.files ? Array.from(e.target.files) : [];
 			if (files.length === 0) return;
 
-			const maxSizeLabel = formatFileSize(MAX_FILE_SIZE_BYTES);
+			const maxSizeLabel = formatFileSize(maxBytes);
 			const errorMessage = LABELS.fileTooLarge(maxSizeLabel);
 
 			const items: FileUploadItem[] = files.map((file) => {
-				if (isFileTooLarge(file)) {
+				if (isFileTooLarge(file, maxBytes)) {
 					onUploadError?.(file, errorMessage);
 					return {
 						file,
@@ -171,23 +182,24 @@ export function useFileUpload(options: UseFileUploadOptions = {}): UseFileUpload
 						continue;
 					}
 
-					if (!publishLocationId) {
-						publishLocationId = recordId ?? (await getCurrentUserId());
+					// Only create ContentVersion if recordId is provided
+					let contentVersionId: string | undefined;
+					if (recordId) {
+						if (!publishLocationId) {
+							publishLocationId = recordId;
+						}
+						setFileItems((prev) =>
+							updateItem(prev, file.name, { state: "creating_record", progress: 100 }),
+						);
+						contentVersionId = await createContentVersion(file, contentBodyId, publishLocationId);
 					}
-					setFileItems((prev) =>
-						updateItem(prev, file.name, { state: "creating_record", progress: 100 }),
-					);
-					const contentVersionId = await createContentVersion(
-						file,
-						contentBodyId,
-						publishLocationId,
-					);
 
 					flushSync(() => {
 						setFileItems((prev) =>
 							updateItem(prev, file.name, {
 								state: "success",
 								progress: 100,
+								contentBodyId,
 								contentVersionId,
 							}),
 						);
@@ -195,6 +207,7 @@ export function useFileUpload(options: UseFileUploadOptions = {}): UseFileUpload
 					uploadedFiles.push({
 						name: file.name,
 						size: file.size,
+						contentBodyId,
 						contentVersionId,
 					});
 				} catch (err) {
@@ -222,7 +235,7 @@ export function useFileUpload(options: UseFileUploadOptions = {}): UseFileUpload
 
 			e.target.value = "";
 		},
-		[recordId, onUploadComplete, onUploadError],
+		[recordId, onUploadComplete, onUploadError, maxBytes],
 	);
 
 	const handleDragOver = React.useCallback((e: React.DragEvent) => {

package/dist/force-app/main/default/webapplications/feature-react-file-upload/src/index.ts

@@ -54,3 +54,21 @@ export { useFileUpload } from "./hooks/useFileUpload";
  * @see useFileUpload
  */
 export type { UseFileUploadOptions } from "./hooks/useFileUpload";
+
+/**
+ * Create ContentVersion record programmatically. Useful when you need to create
+ * ContentVersion separately from the file upload process (e.g., after uploading
+ * file to a different location first).
+ *
+ * @param file - The file to create ContentVersion for
+ * @param contentBodyId - The ContentBody ID from a previous upload
+ * @param recordId - The record ID for FirstPublishLocationId (e.g., Account, Opportunity, or User ID)
+ * @returns ContentVersion ID if successful
+ *
+ * @example
+ * ```tsx
+ * const contentBodyId = await uploadToUrl(file, token, uploadUrl, onProgress);
+ * const contentVersionId = await createContentVersion(file, contentBodyId, recordId);
+ * ```
+ */
+export { createContentVersion, getCurrentUserId } from "./api/fileUpload";