File Input

<wa-file-input> Since 3.2 experimental Pro

File inputs allow users to select files from their device.

File inputs allow users to select one or more files from their device using a dropzone that supports both click and drag-and-drop interactions.

<wa-file-input label="Select a file"></wa-file-input>

This component works with standard <form> elements. Please refer to the section on form controls to learn more about form submission and client-side validation.

Examples

Labels

Use the label attribute to give the file input an accessible label. For labels that contain HTML, use the label slot instead.

<wa-file-input label="Upload your resume"></wa-file-input>

Hints

Add descriptive help text with the hint attribute. For hints that contain HTML, use the hint slot instead.

<wa-file-input
  label="Profile photo"
  hint="Upload a photo to personalize your account."
></wa-file-input>

Multiple Files

Add the multiple attribute to allow the file input to accept more than one file. If the user drops a folder, all files within it will be added to the file input.

<wa-file-input
  label="Upload documents"
  hint="You can select multiple files at once."
  multiple
></wa-file-input>

Accepting File Types

Use the accept attribute to limit the file input to certain file types. Set it to a comma-separated string of unique file type specifiers.

<wa-file-input
  label="Upload an image"
  hint="Only JPEG, PNG, GIF, and WebP images are allowed."
  accept="image/jpeg, image/png, image/gif, image/webp"
></wa-file-input>

You can also use file extensions such as accept="pdf, .doc, .docx".

<wa-file-input
  label="Upload a document"
  hint="PDF and Word documents only."
  accept=".pdf, .doc, .docx"
></wa-file-input>

Disabled

Use the disabled attribute to disable the file input.

<wa-file-input label="Upload disabled" disabled></wa-file-input>

Sizes

Use the size attribute to change the file input's size.



<wa-file-input label="Small" size="small"></wa-file-input>
<br>
<wa-file-input label="Medium" size="medium"></wa-file-input>
<br>
<wa-file-input label="Large" size="large"></wa-file-input>

Custom Dropzone Content

Use the dropzone slot to customize what appears inside the dropzone area.

Drag and drop your files here or click to browse 
<wa-file-input label="Upload files" multiple>
  <div slot="dropzone" style="display: flex; flex-direction: column; align-items: center; gap: 0.5rem;">
    <wa-icon name="cloud-arrow-up" style="font-size: 2.5rem;"></wa-icon>
    <strong>Drag and drop your files here</strong>
    <span style="color: var(--wa-color-neutral-on-quiet);">or click to browse</span>
  </div>
</wa-file-input>

Working with Files

The files property gives you access to an array of selected files. Unlike the native file input's FileList, this is a standard JavaScript array, making it easier to manipulate.


Reverse Order Clear All Log Files 
<wa-file-input
  id="file-input-demo"
  label="Select some files"
  hint="Try the buttons below after selecting files."
  multiple
></wa-file-input>

<br>

<wa-button id="reverse-btn" appearance="filled">Reverse Order</wa-button>
<wa-button id="clear-btn" appearance="filled">Clear All</wa-button>
<wa-button id="log-btn" appearance="filled">Log Files</wa-button>

<script>
  const fileInput = document.getElementById('file-input-demo');
  const reverseBtn = document.getElementById('reverse-btn');
  const clearBtn = document.getElementById('clear-btn');
  const logBtn = document.getElementById('log-btn');

  reverseBtn.addEventListener('click', () => {
    fileInput.files = fileInput.files.toReversed();
  });

  clearBtn.addEventListener('click', () => {
    fileInput.files = [];
  });

  logBtn.addEventListener('click', () => {
    console.log('Selected files:', fileInput.files);
  });
</script>

The files property must be reassigned, not mutated! Avoid using functions that mutate the array, such as reverse() and sort(), because they won't trigger an update. Use non-mutating alternatives like toReversed() and toSorted() instead.

Uploading with Forms

When uploading files from a form, add method="post" and enctype="multipart/form-data" to the form so files are sent correctly to the server.


Upload 
<form
  id="upload-form"
  method="post"
  enctype="multipart/form-data"
  action="about:blank"
>
  <wa-file-input
    name="documents"
    label="Select files to upload"
    multiple
  ></wa-file-input>
  <br>
  <wa-button type="submit" variant="brand">Upload</wa-button>
</form>

<script>
  const form = document.getElementById('upload-form');

  form.addEventListener('submit', event => {
    event.preventDefault();
    const formData = new FormData(form);
    console.log('Files to upload:', [...formData.getAll('documents')]);
  });
</script>

Required Validation

Add the required attribute to make file selection mandatory. Form submission will be blocked until a file is selected.


Submit Reset 
<form id="required-form" action="about:blank" method="get">
  <wa-file-input
    name="file"
    label="Required file"
    hint="You must select a file to submit."
    required
  ></wa-file-input>
  <br>
  <wa-button type="submit" variant="brand">Submit</wa-button>
  <wa-button type="reset" appearance="filled">Reset</wa-button>
</form>

Custom Validation

Use the setCustomValidity() method to set a custom error message. This will override standard validation and prevent form submission. Clear the error by passing an empty string.


Submit Reset 
<form id="custom-validation-form" action="about:blank" method="get">
  <wa-file-input
    id="custom-file-input"
    name="file"
    label="Upload a small file"
    hint="Files must be smaller than 500 KB."
  ></wa-file-input>
  <br>
  <wa-button type="submit" variant="brand">Submit</wa-button>
  <wa-button type="reset" appearance="filled">Reset</wa-button>
</form>

<script type="module">
  const form = document.getElementById('custom-validation-form');
  const fileInput = document.getElementById('custom-file-input');
  const maxSize = 500 * 1024; // 500 KB

  fileInput.addEventListener('change', () => {
    const tooLarge = fileInput.files.some(file => file.size > maxSize);

    if (tooLarge) {
      fileInput.setCustomValidity('One or more files exceed the 500 KB limit.');
    } else {
      fileInput.setCustomValidity('');
    }
  });

  // Don't actually submit in the demo
  form.addEventListener('submit', event => {
    event.preventDefault();
  });
</script>

Styling Validation States

Use the :state(user-valid) and :state(user-invalid) custom states to style the file input based on its validation status. These states only apply after the user has interacted with the control or attempted to submit the form.


Submit Reset 
<form id="styling-form" action="about:blank" method="get" class="validation-styles">
  <wa-file-input
    name="file"
    label="Select a file"
    required
  ></wa-file-input>
  <br>
  <wa-button type="submit" variant="brand">Submit</wa-button>
  <wa-button type="reset" appearance="filled">Reset</wa-button>
</form>

<style>
  .validation-styles wa-file-input:state(user-valid) {
    outline: solid 2px var(--wa-color-success-fill-loud);
    outline-offset: 0.5rem;
  }

  .validation-styles wa-file-input:state(user-invalid) {
    outline: solid 2px var(--wa-color-danger-fill-loud);
    outline-offset: 0.5rem;
  }
</style>

You can also style based on the :state(blank) and :state(dragging) states:

<wa-file-input
  class="drag-styles"
  label="Watch the border change while dragging"
  multiple
></wa-file-input>

<style>
  .drag-styles::part(dropzone) {
    transition: transform 0.2s ease;
  }

  .drag-styles:state(dragging)::part(dropzone) {
    transform: scale(1.02);
  }
</style>

Importing

Autoloading components via projects is the recommended way to import components. If you prefer to do it manually, use one of the following code snippets.

CDN npm React

Let your project code do the work! Sign up for free to use a project with your very own CDN — it's the fastest and easiest way to use Web Awesome.

To manually import this component from NPM, use the following code. 

import '@awesome.me/webawesome/dist/components/file-input/file-input.js';

To manually import this component from React, use the following code. 

import WaFileInput from '@awesome.me/webawesome/dist/react/file-input';

Slots

Learn more about using slots.

Attributes & Properties

Learn more about attributes and properties.

Methods

Learn more about methods.

Events

Learn more about events.

Custom States

Learn more about custom states.

CSS parts

Learn more about CSS parts.

Dependencies

This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.

Need a hand? Report a bug Ask for help
    No results
    Navigate Enter Select Esc Close