--- schema_version: "1" id: 88d301fc866a8ab0bccb4f2f59c6291cf3fd34d992180fc504615cb028660d72 title: File Upload collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/fileUpload/lightning-file-upload.md canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-file-upload.html source_site: developer.salesforce.com content_type: documentation content_hash: f13e87b904f0c4c13ae3f853a93dea80983eb3519d57a23c5ff904c3f8ad7146 products: - Lightning Component Reference --- # File Upload **`lightning-file-upload`** A file uploader for uploading and attaching files to records. **For Use In** Lightning Experience, Experience Builder Sites, Salesforce Mobile App ::::::tabset{tabs='[ "Develop", "Specifications"]'} :::::tab 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. ```html ``` 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. ```javascript import { LightningElement, api } from "lwc"; export default class FileUploadExample extends LightningElement { @api myRecordId; get acceptedFormats() { return [".pdf", ".png"]; } handleUploadFinished(event) { // Get the list of uploaded files const uploadedFiles = event.detail.files; alert("No. of files uploaded : " + uploadedFiles.length); } } ``` 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. ## Design `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. | | SLDS 1 | SLDS 2 | | :------------- | :------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- | | **Design** | [File Selector](https://v1.lightningdesignsystem.com/components/file-selector/) | [File Selector](https://www.lightningdesignsystem.com/components/file-selector/) | | **For Use In** | Lightning Experience, Experience Builder Sites, Salesforce Mobile App | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) | To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute. ## File Upload Limits 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](https://help.salesforce.com/s/articleView?id=commerce.comm_configure_cdn_and_custom_domains.htm). The allowed file size limits and types also follow the settings determined by site file moderation. ## Enable Guest Users to Upload Files 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. ```html ``` 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`. ```javascript import { LightningElement, api } from "lwc"; export default class FileUploadExample extends LightningElement { @api myRecordId; get encryptedToken() { //use apex to get } get acceptedFormats() { return [".pdf", ".png"]; } handleUploadFinished(event) { // Get the list of uploaded files const uploadedFiles = event.detail.files; alert("No. of files uploaded : " + uploadedFiles.length); } } ``` When guest users upload files, the component returns `ContentVersionId` and not `ContentDocumentId`. For more information, see [Files Best Practices and Considerations for Guest Users](https://help.salesforce.com/articleView?id=networks_files_best_practices.htm&type=0) in Salesforce Help. ## Usage Considerations `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](https://help.salesforce.com/s/articleView?id=experience.admin_files_type_security.htm) 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 For external users, the component doesn't follow an object's org-wide default (OWD) settings and instead relies on the sharing hierarchy. Even when an object's OWD is set to Public Read/Write, external users can't add files to the object. To provide access for external users, [create a sharing set](https://help.salesforce.com/s/articleView?id=platform.networks_setting_light_users.htm). ## Custom Events **`uploadfinished`** The event fired when files are uploaded successfully. The `uploadfinished` event returns the following parameter. | Parameter | Type | Description | | --------- | ------ | ------------------------------------ | | files | object | The list of files that are uploaded. | `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. | Property | Value | Description | | ---------- | ----- | --------------------------------------------------------------------------------------------------------- | | bubbles | false | This event doesn't bubble. | | cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. | | composed | false | This event doesn't propagate outside the template in which it was dispatched. | ## See Also [_Salesforce Help_: Configure File Upload and Download Security Settings](https://help.salesforce.com/s/articleView?language=en_US&id=experience.admin_files_type_security.htm) [_Salesforce Help_: Files Best Practices and Considerations for Guest Users](https://help.salesforce.com/articleView?id=networks_files_best_practices.htm) [_Salesforce Help_: Sharing Rule Types](https://help.salesforce.com/articleView?id=platform.security_sharing_rule_types.htm) [Guest User Record Access Development Best Practices](https://www.learnexperiencecloud.com/s/article/Guest-User-Record-Access-Development-Best-Practices) ::::: :::::tab ::component-specification{component="fileUpload" model="lwc" namespace="lightning"} ::::: ::::::