File Upload

A lightning-file-upload component provides an integrated way for users to upload multiple files. You can configure the file uploader to accept specific file types, and the file types are filtered in the user's file browser. To upload files by using lightning-file-upload, you can:

• Click the button to select a file from your system's file browser
• Drag a file from your system into the file selector drop zone

To associate an uploaded file with a record, specify the record-id attribute. Uploaded files are available in several locations:

• Files Home under the Owned by Me filter
• On the record's Attachments related list that's on the record detail page

If you don't specify the record-id attribute, the file is private to the uploading user.

Although all Salesforce-supported file formats are allowed, you can restrict the file formats by using the accept attribute.

The button label is "Upload Files" by default. Use the label attribute to add a descriptive label above the Upload Files button.

This example creates a file uploader that allows you to upload multiple PDF and PNG files.

You must handle the uploadfinished event, which is fired when the upload is finished to return a list of the uploaded files, including each file's name and documentId.

After you select the files to upload, the Upload Files dialog shows the upload progress. You can dismiss it by clicking the x icon or the Done button.

Use the event handler to customize what happens after your files upload successfully and the Upload Files dialog is dismissed, such as showing a toast by using the lightning/platformShowToastEvent module.

If your record page shows the Notes & Attachments panel, your uploaded files automatically appear there after the page is refreshed.

lightning-file-upload implements the file selector blueprint in the Salesforce Lightning Design System (SLDS). The file selector adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

To apply additional styling, use the SLDS utility classes with the class attribute.

By default, you can upload up to 10 files simultaneously unless your Salesforce admin has changed that limit. The org limit for the number of files simultaneously uploaded is a minimum of 1 file and a maximum of 25 files. The maximum file size that you can upload is 10 GB.

In Experience Builder sites, the file size limits are lower than the default 10 GB, and they depend on your site’s URL configuration. If you use the my.site.com URL provided by Salesforce, the size limit per file is 128 MB. If you create a custom domain, the size limit is 500 MB. For more information, see Configure a Custom Domain and CDN in Salesforce Help. The allowed file size limits and types also follow the settings determined by site file moderation.

By default, guest users can’t upload files and don’t have access to objects and their related records.

To enable guest users to upload files, enable the org preference Allow site guest users to upload files. From Setup, in the Quick Find box, enter Salesforce Files, and select General Settings. Select Allow site guest users to upload files. However, even if you enable this setting, guest users can upload files to a record only when guest user sharing rules are in place.

To use lightning-file-upload for LWR sites with LWR and guest enabled sites, you must also select Use the File Upload Lightning web component for LWR sites.

The Secure guest user record access org preference prevents access to records by guest users. As a result, if you specify the record-id in the lightning-file-upload component, the file fails to upload because the guest user doesn't have access to the record.

To enable guest users to upload files to a record, the org admin can create a custom field on the ContentVersion object. The field type can be text or picklist. The API name of the custom field must end with fileupload__c. For example, you can use the API name Guest_Record_fileupload__c for the custom field.

Specify the file-field-name and file-field-value attributes in lightning-file-upload to store a value in the custom field in the ContentVersion object. For example, set file-field-name to Guest_Record_fileupload__c. Set file-field-value to a value that can be used in Apex to associate the file to the record.

You can omit the record-id attribute when specifying file-field-name and file-field-value attributes. However, if you provide the record-id, file-field-name and file-field-value attributes, the record ID is ignored if the uploading user is a guest user.

If you don't provide the record-id or file-field-name and file-field-value attributes, the uploaded file is private to an authenticated user.

This example specifies record-id, file-field-name, and file-field-value attributes for behavior that supports authenticated users and guest users for uploading files to records.

Use Apex in your JavaScript file to get the value of the custom field.

The uploadfinished event is fired when the upload is finished to return a list of the uploaded files, including each file's name and documentId. When a guest user uploads files, the returned list includes only the names of the files and doesn't return documentId.

When guest users upload files, the component returns ContentVersionId and not ContentDocumentId.

For more information, see Files Best Practices and Considerations for Guest Users in Salesforce Help.

lightning-file-upload doesn't support uploading multiple files at once on Android devices.

This component isn't supported in Lightning Out or standalone apps, and displays as a disabled input. Additionally, if the Don't allow HTML uploads as attachments or document records security setting is enabled for your organization, the file uploader can't be used to upload files with the following file extensions: .htm, .html, .htt, .htx, .mhtm, .mhtml, .shtm, .shtml, .acgi, .svg. For more information, see Configure File Upload and Download Security Settings in Salesforce Help.

If an error is detected on the client side, the file upload dialog shows an informative error message. For example, the message informs you if you try to upload a file type that isn't on the accept list. If an error is detected on the server side, you see a generic "Can't upload file" error. For example, you get this error if you don't provide a valid record ID or the upload violates a validation rule.

We recommend that you add one or more record types to the ContentVersion object in your org. When record types are present, the file uploader enables you to provide details about the file and shows any error messages from the server. This feature is useful if your org uses Apex triggers or validation rules for file uploads, or has required custom fields in the ContentVersion object. You can fix errors or provide required information to complete the upload without reuploading the file.

On mobile devices, file upload doesn't work correctly when there's a required custom field in the ContentVersion object. To avoid this limitation, try one of these workarounds.

• Make the custom field optional
• Set a default value for the custom field
• Use code to populate the field after file upload

uploadfinished

The event fired when files are uploaded successfully.

The uploadfinished event returns the following parameter.

event.detail.files returns a list of uploaded files with the attributes name and documentId. If a guest user performed the file upload, the documentId isn't returned.

• name: The file name in the format filename.extension, for example, account.jpg.
• documentId: The ContentDocument Id in the format 069XXXXXXXXXXXX.

The event properties are as follows.

Salesforce Help: Configure File Upload and Download Security Settings

Salesforce Help: Files Best Practices and Considerations for Guest Users

Salesforce Help: Sharing Rule Types

Guest User Record Access Development Best Practices