file-input

Version: 2.0.0

Summary

A better <input type="file">.

What's wrong with <input type="file">?

  1. It's difficult to skin/style as the look and feel of the element is mostly determined by the user agent.
  2. Access to the selected files are provided via FileList object, which is a pseudo-array (not a "real" array, with useful sugar like forEach, etc).
  3. You want any sort of file validation? Do it yourself!
  4. The API is lacking in many respects.
Now, a new, better, evolved (and evolving) element to take its place: <file-input>!

And... <file-input> integrates perfectly with <ajax-form>!

Simply include a <file-input> in an <ajax-form>, ensure the name attribute is present on the <file-input>, and the <ajax-form> includes an enctype attriute with a value of multipart/form-data. Any valid files will be sent along with the other form fields! 
If you incoude a required attribute on the <file-input>, <ajax-form> will even prevent the form from being submitted if there isn't at least one valid file selected! Note that the validation of custom elements, such as <file-input>, will first be possible in <ajax-form> 1.3.0.
DON'T FORGET TO VULCANIZE YOUR MAIN/PARENT HTML FILE BEFORE DEPLOYING INTO PRODUCTION. THIS WILL ENSURE THAT ALL OF YOUR HTML IMPORTS ARE CONCATENATED INTO ONE FILE.

Attributes

accept
<string>
If you want to restrict the types of files that the file chooser will allow your user's to select, you can make use of an accept attribute, passing one or more MIME types as comma-separated values.
Please note that browser support for this attribute is poor and implementations vary. 
For example, to only allow your users to select images and videos: 
<file-input accept="image/*,video/*">
    Select Files
</file-input>
camera
<>
This is currently an iOS-specific attribute, as there are a few attributes on the underlying <input type="file"> element that must be setup in order to allow camera access on Apple mobile devices. <file-input> is smart enough to only apply these settings when neceessary (only when the device is running iOS), so including this property on other devices is essentially a NOP.
<file-input camera>
    Select Files
</file-input>
directory
<>
Some browsers (currently only Chrome and Opera) allow you to select folders for upload. To turn on this feature (ignored if not supported by the UA), just include this attribute on the element.
<file-input directory>
    Select Files
</file-input>
Note: Using this feature may not be a great idea for large directories (or high-latency file systems) since the UI thread is blocked while the file tree is parsed. This is an unfortunate native implementation detail in the browser.
invalidText
<string>default: "No valid files selected."
Text that will appear next to the element if an <ajax-form> submission is rejected due to an invalid <file-input>. 
extensions
<Array>
This is a validation attribute that allows you to filter out any files that do not contain a specific extension. The value of this attribute is a JSON array string, containing all extensions to keep.
You can also negate your extension array by including a ! sign just before the array's opening bracket.
For example, to only accept "jpeg" files:
<file-input extensions='["jpeg", "jpg"]'>
    Select Files
</file-input>
To allow any extension EXCEPT "jpeg" files:
<file-input extensions='!["jpeg", "jpg"]'>
    Select Files
</file-input>
maxFiles
<integer>default: 0
If you'd like to limit the number of files to accept from your users, specify this as an integer value for the maxFiles attribute.
For example, to only accept 3 files:
<file-input maxFiles="3">
    Select Files
</file-input>
If you'd like to completely prevent users from selecting more than one file from the file chooser, you can simply set maxFiles to 1:
<file-input maxFiles="1">
    Select Files
</file-input>
maxSize & minSize
<integer>default: 0
You can also specify maximum and minimum acceptable file sizes for the purposes of validation. The values of each attribute are expected to be in bytes.
For example, to only allow files that are 1000 bytes or greater but not greater than 3000 bytes:
<file-input minSize="1000" maxSize="3000">
    Select Files
</file-input>
required
<>
Include this attribute if this element is embedded in an <ajax-form> and you want to prevent submission unless at least one valid file has been selected.
<file-input required>
    Select Files
</file-input>

Properties

files
<Array>default: []
To access an Array of File objects selected by your user that have also passed all validation checks, look to the files property.
var validFiles = fileInputElement.files;
invalid
<Object>default: {count: 0}
To access an Object containing keyed Arrays of File objects, representing any files selected by your user that did not pass validation checks, inspect the invalidproperty. 
This is an object with a count property to easily determine how many invalid files exist. Invalid files are grouped by reason.
For example, if there are 4 invalid files, one of each type: the value of the invalidproperty would look like this:
var invalidFiles = fileInputEl.invalid;

expect(invalidFiles).toEqual({
    count: 4,

    // array containing the 1 file
    // with a bad extension
    badExtension: [],

    // array containing the 1 file with
    // a file size that was too large
    tooBig: [],

    // array containing the 1 file with
    // a file size that was too small
    tooSmall: [],

    // array containing any leftover
    // otherwise valid files that exceed
    // the number of allowable files
    tooMany: []
});

Events

change
When your user selects new files, a "change" event will be triggered on the element. The detail property on the event passed to your handler will contain two properties: valid and invalid.
These correspond to the files and invalid (respectively) properties on the element instance.
fileInputEl.addEventListener("change",
    function(event) {
        var validFiles = event.detail.valid,
            invalidFiles = event.detail.invalid;

        // handle the event
    }
);

Methods

reset
To reset the files and invalid cache and also reset the underlying <input type="file">, use the reset() function:
document.querySelector("file-input").reset();