@salesforce/webapp-template-feature-react-file-upload-experimental 1.60.1 → 1.61.0

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.61.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.60.2...v1.61.0) (2026-03-02)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
+## [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

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.60.0",
-      "resolved": "https://registry.npmjs.org/@salesforce/sdk-core/-/sdk-core-1.60.0.tgz",
-      "integrity": "sha512-W6efNzdRfv4NM7urU/lCjRJJ9DQSEHl1xTtts2l/XjlgNFG2MIHr9D/EGuMbtRKgqV0cU5SE/HekRNCdYxNaGQ==",
+      "version": "1.60.2",
+      "resolved": "https://registry.npmjs.org/@salesforce/sdk-core/-/sdk-core-1.60.2.tgz",
+      "integrity": "sha512-XZJYBxJwHPbahfyL86FI2ChYT7is+ZoiM1M4lTNZtt9me7j9AhMTVf7kpIbAX6ye1/ROEaLlAz9TAdCQMll2Rg==",
       "license": "SEE LICENSE IN LICENSE.txt"
     },
     "node_modules/@salesforce/sdk-data": {
-      "version": "1.60.0",
-      "resolved": "https://registry.npmjs.org/@salesforce/sdk-data/-/sdk-data-1.60.0.tgz",
-      "integrity": "sha512-zlqudhAqHfe5pufEsaTHG+e0WirRR36Mjbd9iaMyeo6nnG3F8Gb6mselJY+5qQ9R+JtqLSiZLxgmHCp1aqv9Wg==",
+      "version": "1.60.2",
+      "resolved": "https://registry.npmjs.org/@salesforce/sdk-data/-/sdk-data-1.60.2.tgz",
+      "integrity": "sha512-q4frWaRD2J3yOT81NPuq/qck8W3JfzdOmRrBvM8/aQ6RwPlxkJXwhq1PR3PgdmKWX5n49VksmxorZA23ttbdjA==",
       "license": "SEE LICENSE IN LICENSE.txt",
       "dependencies": {
         "@conduit-client/salesforce-lightning-service-worker": "^3.7.0",
-        "@salesforce/sdk-core": "^1.60.0"
+        "@salesforce/sdk-core": "^1.60.2"
       }
     },
     "node_modules/@salesforce/ts-types": {
@@ -6096,15 +6096,15 @@
       }
     },
     "node_modules/@salesforce/vite-plugin-webapp-experimental": {
-      "version": "1.60.0",
-      "resolved": "https://registry.npmjs.org/@salesforce/vite-plugin-webapp-experimental/-/vite-plugin-webapp-experimental-1.60.0.tgz",
-      "integrity": "sha512-T3UkicN5pOnZxFtdPkJBVhmXvUJvWHMs849ISAykNH8LumgeajeRbRgx9/c4drMIGRSXVA8JQVSJjVnDTpK3Sg==",
+      "version": "1.60.2",
+      "resolved": "https://registry.npmjs.org/@salesforce/vite-plugin-webapp-experimental/-/vite-plugin-webapp-experimental-1.60.2.tgz",
+      "integrity": "sha512-/woKAsjTLIjrVWNCRy5PQS+I84RbBDdIvX84X0YEBF6mKrD5oQPTOw9U6ERxsVQGwux3K3vNwHyof2HmdHMIZg==",
       "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.60.0"
+        "@salesforce/webapp-experimental": "^1.60.2"
       },
       "engines": {
         "node": ">=20.0.0"
@@ -6114,13 +6114,13 @@
       }
     },
     "node_modules/@salesforce/webapp-experimental": {
-      "version": "1.60.0",
-      "resolved": "https://registry.npmjs.org/@salesforce/webapp-experimental/-/webapp-experimental-1.60.0.tgz",
-      "integrity": "sha512-XfcAv+l5qgiBEfMSw5UqLvy/cVjFvkBlkQduf8aHhsGufaMsRuSfSdvxdOlTDLGz5/ThBFA+1SmILeW4q2n/dw==",
+      "version": "1.60.2",
+      "resolved": "https://registry.npmjs.org/@salesforce/webapp-experimental/-/webapp-experimental-1.60.2.tgz",
+      "integrity": "sha512-n96PoDAVdFt1G9fJezcor0r/WMnS8UktvqBsOEetp/v9NxhZISUJo5fQUgl3mW876FnILaCyV1muxkKKXuH7/A==",
       "license": "SEE LICENSE IN LICENSE.txt",
       "dependencies": {
         "@salesforce/core": "^8.23.4",
-        "@salesforce/sdk-data": "^1.60.0",
+        "@salesforce/sdk-data": "^1.60.2",
         "axios": "^1.7.7",
         "micromatch": "^4.0.8",
         "path-to-regexp": "^8.3.0"
@@ -6755,9 +6755,9 @@
       "license": "MIT"
     },
     "node_modules/@types/node": {
-      "version": "24.10.15",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-24.10.15.tgz",
-      "integrity": "sha512-BgjLoRuSr0MTI5wA6gMw9Xy0sFudAaUuvrnjgGx9wZ522fYYLA5SYJ+1Y30vTcJEG+DRCyDHx/gzQVfofYzSdg==",
+      "version": "24.11.0",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-24.11.0.tgz",
+      "integrity": "sha512-fPxQqz4VTgPI/IQ+lj9r0h+fDR66bzoeMGHp8ASee+32OSGIkeASsoZuJixsQoVef1QJbeubcPBxKk22QVoWdw==",
       "devOptional": true,
       "license": "MIT",
       "dependencies": {
@@ -8206,9 +8206,9 @@
       }
     },
     "node_modules/caniuse-lite": {
-      "version": "1.0.30001774",
-      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001774.tgz",
-      "integrity": "sha512-DDdwPGz99nmIEv216hKSgLD+D4ikHQHjBC/seF98N9CPqRX4M5mSxT9eTV6oyisnJcuzxtZy4n17yKKQYmYQOA==",
+      "version": "1.0.30001775",
+      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001775.tgz",
+      "integrity": "sha512-s3Qv7Lht9zbVKE9XoTyRG6wVDCKdtOFIjBGg3+Yhn6JaytuNKPIjBMTMIY1AnOH3seL5mvF+x33oGAyK3hVt3A==",
       "funding": [
         {
           "type": "opencollective",
@@ -8378,14 +8378,14 @@
       }
     },
     "node_modules/cli-truncate": {
-      "version": "5.1.1",
-      "resolved": "https://registry.npmjs.org/cli-truncate/-/cli-truncate-5.1.1.tgz",
-      "integrity": "sha512-SroPvNHxUnk+vIW/dOSfNqdy1sPEFkrTk6TUtqLCnBlo3N7TNYYkzzN7uSD6+jVjrdO4+p8nH7JzH6cIvUem6A==",
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/cli-truncate/-/cli-truncate-5.2.0.tgz",
+      "integrity": "sha512-xRwvIOMGrfOAnM1JYtqQImuaNtDEv9v6oIYAs4LIHwTiKee8uwvIi363igssOC0O5U04i4AlENs79LQLu9tEMw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "slice-ansi": "^7.1.0",
-        "string-width": "^8.0.0"
+        "slice-ansi": "^8.0.0",
+        "string-width": "^8.2.0"
       },
       "engines": {
         "node": ">=20"
@@ -8980,9 +8980,9 @@
       "license": "MIT"
     },
     "node_modules/dedent": {
-      "version": "1.7.1",
-      "resolved": "https://registry.npmjs.org/dedent/-/dedent-1.7.1.tgz",
-      "integrity": "sha512-9JmrhGZpOlEgOLdQgSm0zxFaYoQon408V1v49aqTWuXENVlnCuY9JBZcXZiCsZQWDjTm5Qf/nIvAy77mXDAjEg==",
+      "version": "1.7.2",
+      "resolved": "https://registry.npmjs.org/dedent/-/dedent-1.7.2.tgz",
+      "integrity": "sha512-WzMx3mW98SN+zn3hgemf4OzdmyNhhhKz5Ay0pUfQiMQ3e1g+xmTJWp/pKdwKVXhdSkAEGIIzqeuWrL3mV/AXbA==",
       "license": "MIT",
       "peerDependencies": {
         "babel-plugin-macros": "^3.1.0"
@@ -9317,9 +9317,9 @@
       }
     },
     "node_modules/enhanced-resolve": {
-      "version": "5.19.0",
-      "resolved": "https://registry.npmjs.org/enhanced-resolve/-/enhanced-resolve-5.19.0.tgz",
-      "integrity": "sha512-phv3E1Xl4tQOShqSte26C7Fl84EwUdZsyOuSSk9qtAGyyQs2s3jJzComh+Abf4g187lUUAvH+H26omrqia2aGg==",
+      "version": "5.20.0",
+      "resolved": "https://registry.npmjs.org/enhanced-resolve/-/enhanced-resolve-5.20.0.tgz",
+      "integrity": "sha512-/ce7+jQ1PQ6rVXwe+jKEg5hW5ciicHwIQUagZkp6IufBoY3YDgdTTY1azVs0qoRgVmvsNB+rbjLJxDAeHHtwsQ==",
       "license": "MIT",
       "dependencies": {
         "graceful-fs": "^4.2.4",
@@ -13238,6 +13238,23 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/log-update/node_modules/slice-ansi": {
+      "version": "7.1.2",
+      "resolved": "https://registry.npmjs.org/slice-ansi/-/slice-ansi-7.1.2.tgz",
+      "integrity": "sha512-iOBWFgUX7caIZiuutICxVgX1SdxwAVFFKwt1EvMYYec/NWO5meOJ6K5uQxhrYBdQJne4KxiqZc+KptFOWFSI9w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^6.2.1",
+        "is-fullwidth-code-point": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/slice-ansi?sponsor=1"
+      }
+    },
     "node_modules/log-update/node_modules/string-width": {
       "version": "7.2.0",
       "resolved": "https://registry.npmjs.org/string-width/-/string-width-7.2.0.tgz",
@@ -14921,9 +14938,9 @@
       "license": "MIT"
     },
     "node_modules/pump": {
-      "version": "3.0.3",
-      "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.3.tgz",
-      "integrity": "sha512-todwxLMY7/heScKmntwQG8CXVkWUOdYxIvY2s0VWAAMh/nd8SoYiRaKjlr7+iCs984f2P8zvrfWcDDYVb73NfA==",
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.4.tgz",
+      "integrity": "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA==",
       "license": "MIT",
       "dependencies": {
         "end-of-stream": "^1.1.0",
@@ -15690,9 +15707,9 @@
       "license": "MIT"
     },
     "node_modules/sax": {
-      "version": "1.4.4",
-      "resolved": "https://registry.npmjs.org/sax/-/sax-1.4.4.tgz",
-      "integrity": "sha512-1n3r/tGXO6b6VXMdFT54SHzT9ytu9yr7TaELowdYpMqY/Ao7EnlQGmAQ1+RatX7Tkkdm6hONI2owqNx2aZj5Sw==",
+      "version": "1.5.0",
+      "resolved": "https://registry.npmjs.org/sax/-/sax-1.5.0.tgz",
+      "integrity": "sha512-21IYA3Q5cQf089Z6tgaUTr7lDAyzoTPx5HRtbhsME8Udispad8dC/+sziTNugOEx54ilvatQ9YCzl4KQLPcRHA==",
       "license": "BlueOak-1.0.0",
       "engines": {
         "node": ">=11.0.0"
@@ -16353,17 +16370,17 @@
       }
     },
     "node_modules/slice-ansi": {
-      "version": "7.1.2",
-      "resolved": "https://registry.npmjs.org/slice-ansi/-/slice-ansi-7.1.2.tgz",
-      "integrity": "sha512-iOBWFgUX7caIZiuutICxVgX1SdxwAVFFKwt1EvMYYec/NWO5meOJ6K5uQxhrYBdQJne4KxiqZc+KptFOWFSI9w==",
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/slice-ansi/-/slice-ansi-8.0.0.tgz",
+      "integrity": "sha512-stxByr12oeeOyY2BlviTNQlYV5xOj47GirPr4yA1hE9JCtxfQN0+tVbkxwCtYDQWhEKWFHsEK48ORg5jrouCAg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "ansi-styles": "^6.2.1",
-        "is-fullwidth-code-point": "^5.0.0"
+        "ansi-styles": "^6.2.3",
+        "is-fullwidth-code-point": "^5.1.0"
       },
       "engines": {
-        "node": ">=18"
+        "node": ">=20"
       },
       "funding": {
         "url": "https://github.com/chalk/slice-ansi?sponsor=1"

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",