File Selector

An input field for selecting files to upload using an Upload Files button or a drag-and-drop zone. This field accepts files up to 3.5 MB.

To retrieve the list of selected files, use event.target.files in the onchange event handler.

1<template>
2  <lightning-input
3    type="file"
4    label="Attachment"
5    accept="image/png, .zip"
6    onchange={handleFilesChange}
7    multiple
8  >
9  </lightning-input>
10</template>

lightning-input implements designs in the Salesforce Lightning Design System (SLDS). The input types adapt to SLDS 1 or SLDS 2 styling based on the org’s theme or the container app that you use.

Selected files are returned in a FileList object, each specified as a File object with the size and type attributes.

• lastModified
• lastModifiedDate
• name
• size
• type

For more information on the File object, see MDN web docs: Getting information on selected files.

To handle file uploads in your org, wire up your component to an Apex controller that creates a ContentVersion and ContentVersionLink object.

Alternatively, use the lightning-file-upload component for an integrated way to upload files to records.

To programmatically add a file, assign the file input to a FileList object, a File object, or an array of File objects. For example, you can add a new file to the files that are already attached.

1handleAttachFiles() {
2    // Create a reference to lightning-input lwc:ref="inputFile"
3    const myFileField = this.refs.inputFile;
4
5    // Create a File object
6    const myFile = new File(['test content'], 'test.txt', { type: 'text/plain' });
7
8    // Add the new file to existing files
9    const currentFiles = myFileField.files ? Array.from(myFileField.files) : [];
10    myFileField.files = [...currentFiles, myFile];
11}

To remove all files from the file list, use one of these methods.

1// Method 1: Clear files using DataTransfer
2myFileField.files = new DataTransfer().files;
3
4// Method 2: Clear files using an empty array
5myFileField.files = [];

To validate file selection, use the required attribute to ensure at least one file is selected. Use the accept attribute to restrict file types, and validate file size in the onchange event handler.

1<template>
2    <lightning-input
3        type="file"
4        label="Upload Document"
5        accept=".pdf,.doc,.docx"
6        required
7        multiple
8        lwc:ref="documentUpload"
9        onchange={handleFilesChange}
10        message-when-value-missing="Please select at least one file"
11    >
12    </lightning-input>
13  <lightning-button label="Submit" onclick={handleSubmit}></lightning-button>
14</template>

To validate file selection, check the file list, file types, and file sizes. If the selected file isn’t valid, the reportValidity() method shows the error message below the file selector.

1import { LightningElement } from "lwc";
2
3export default class FileValidation extends LightningElement {
4  maxFileSize = 3500000; // 3.5 MB
5
6  handleFilesChange(event) {
7    const files = event.target.files;
8    if (files.length === 0) {
9      return;
10    }
11
12    const fileInput = this.refs.documentUpload;
13
14    // Validate file sizes
15    for (let file of files) {
16      if (file.size > this.maxFileSize) {
17        // Display error message
18        fileInput.setCustomValidity(`File ${file.name} exceeds the maximum size of 3.5 MB`);
19        fileInput.reportValidity();
20        return;
21      }
22    }
23
24    fileInput.setCustomValidity("");
25    // Proceed with file upload
26  }
27
28  handleSubmit() {
29    const fileInput = this.refs.documentUpload;
30    console.log(fileInput.validity.valid); // Returns true or false
31    if (!fileInput.checkValidity()) {
32      fileInput.reportValidity();
33      return;
34    }
35    // Proceed with form submission
36  }
37}

The validity attribute returns an object with read-only boolean properties. For the file type, these attributes apply:

• badInput - Indicates that the value is invalid for any input type
• customError - Indicates that a custom error has been set using setCustomValidity()
• valueMissing - Indicates that no file is selected when the required attribute is set
• valid - True if none of the preceding properties are true

The component links the label attribute you provide with a unique ID on the file selector using the aria-labelledby attribute. The for attribute is also used to link the “Or drop files” label in the drop zone to the file selector.

If you use the label-hidden variant, the label attribute maintains the unique ID on the file selector using the aria-labelledby attribute. The component also maintains the for attribute to link between the file selector and the drop zone label.

If you use the field-level-help attribute, the component creates an aria-describedby link between the file selector and the help tooltip.

If the file selector fails validation, the component adds aria-invalid="true" and links the error message to the input by using aria-describedby.

For additional ARIA attributes that you can use, see the lightning-input Specifications tab.

Use these keys for keyboard navigation on the file selector.

• Tab key: Users can tab to the “Choose Files” button.
• Enter or Space key: Opens the standard OS file selector dialog

After the file selector dialog closes, focus returns to the component, preventing you from losing your place on the page.

change

The event fired when a value is changed in the input field.

The change event returns one of the following event.target parameters, depending on input type.

The event properties are as follows.

lightning-input

For this component’s attributes and methods, see the lightning-input Specifications tab.