---
schema_version: "1"
id: 19447b99aac99a33b5eb6b893c0da38048b89fc6c845a8e90d7a603cb9470b02
title: File Selector
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/fileSelector/lightning-file-selector.md
canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-file-selector.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 3578ead0a93768f159e82c029f0b259d1cf4d4502843d2826a8879ea02abd468
products:
  - Lightning Component Reference
---

# File Selector

**`lightning-input`**
_type="file"_

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="fileSelector" model="lwc" namespace="lightning"}


:::::

:::::tab

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.

<!-- prettier-ignore-start -->
```html
<template>
  <lightning-input
    type="file"
    label="Attachment"
    accept="image/png, .zip"
    onchange={handleFilesChange}
    multiple
  >
  </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-input` implements designs in the Salesforce Lightning Design System (SLDS). The input types adapt to SLDS 1 or [SLDS 2 styling](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm) based on the org's theme or the container app that you use.

| Input Type | SLDS 1                                                                          | SLDS 2                                                                           |
| ---------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| file       | [File Selector](https://v1.lightningdesignsystem.com/components/file-selector/) | [File Selector](https://www.lightningdesignsystem.com/components/file-selector/) |

## Usage

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](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/file).

To handle file uploads in your org, wire up your component to an Apex controller that creates a [ContentVersion](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_contentversion.htm) and [ContentVersionLink](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_contentdocumentlink.htm) object.

Alternatively, use the
[`lightning-file-upload`](/docs/platform/lightning-component-reference/guide/lightning-file-upload.html) 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.

```javascript
 handleAttachFiles() {
    // Create a reference to lightning-input lwc:ref="inputFile"
    const myFileField = this.refs.inputFile;

    // Create a File object
    const myFile = new File(['test content'], 'test.txt', { type: 'text/plain' });

    // Add the new file to existing files
    const currentFiles = myFileField.files ? Array.from(myFileField.files) : [];
    myFileField.files = [...currentFiles, myFile];
}
```

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

```javascript
// Method 1: Clear files using DataTransfer
myFileField.files = new DataTransfer().files;

// Method 2: Clear files using an empty array
myFileField.files = [];
```

## Input Validation

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.

<!-- prettier-ignore -->
```html
<template>
    <lightning-input
        type="file"
        label="Upload Document"
        accept=".pdf,.doc,.docx"
        required
        multiple
        lwc:ref="documentUpload"
        onchange={handleFilesChange}
        message-when-value-missing="Please select at least one file"
    >
    </lightning-input>
  <lightning-button label="Submit" onclick={handleSubmit}></lightning-button>
</template>
```

**note:** For the default error messages, see the [`lightning-input` documentation](/docs/platform/lightning-component-reference/guide/lightning-input.html).

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.

```javascript
import { LightningElement } from "lwc";

export default class FileValidation extends LightningElement {
  maxFileSize = 3500000; // 3.5 MB

  handleFilesChange(event) {
    const files = event.target.files;
    if (files.length === 0) {
      return;
    }

    const fileInput = this.refs.documentUpload;

    // Validate file sizes
    for (let file of files) {
      if (file.size > this.maxFileSize) {
        // Display error message
        fileInput.setCustomValidity(`File ${file.name} exceeds the maximum size of 3.5 MB`);
        fileInput.reportValidity();
        return;
      }
    }

    fileInput.setCustomValidity("");
    // Proceed with file upload
  }

  handleSubmit() {
    const fileInput = this.refs.documentUpload;
    console.log(fileInput.validity.valid); // Returns true or false
    if (!fileInput.checkValidity()) {
      fileInput.reportValidity();
      return;
    }
    // Proceed with form submission
  }
}
```

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

## Accessibility

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](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).

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.

## Custom Events

**`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.

| Parameter | Type   | Description                                                                                                                                                 |
| --------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| files     | Object | For input type `file`, the list of selected files returned in a `FileList` object, each specified as a `File` object with the `size` and `type` attributes. |
| value     | string | For other input types, returns the input value.                                                                                                             |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

## See Also

[`lightning-input`](/docs/platform/lightning-component-reference/guide/lightning-input.html)


:::::

:::::tab
For this component's attributes and methods, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).


:::::

::::::