A functional component that manages the upload process of multiple files.

Special Attributes

Child elements of <coral-fileupload> can be given special attributes to enable functionality.

  • [coral-fileupload-select] - Click to choose file(s), replacing existing files
  • [coral-fileupload-dropzone] - Drag & drop files to choose file(s), replacing existing files
  • [coral-fileupload-clear] - Click to remove all files from the queue
  • [coral-fileupload-submit] - Click to start uploading
  • [coral-fileupload-abort] - Click to abort all uploads
  • [coral-fileupload-abortfile="filename.txt"] - Click to abort a specific file, leaving it in the queue
  • [coral-fileupload-removefile="filename.txt"] - Click to remove a specific file from the queue
  • [coral-fileupload-uploadfile="filename.txt"] - Click to start uploading a specific file

Elements with one of the abort attributes will recieve the following CSS classes based on the state of the FileUpload:

  • is-disabled - Applied when the FileUpload is disabled
  • is-required - Applied when the FileUpload is required
  • is-invalid - Applied when the FileUpload is invalid
  • is-readOnly - Applied when the FileUpload is readOnly
  • is-dragging - Applied to elements matching [coral-fileupload-dropzone] when a file is being dragged

Additionally, these elements with have their disabled property toggled as necessary.

Asynchronous Usage: In place of a <form>

The FileUpload component can be used in place of a <form> tag to upload files asynchronously.

Simply add the <coral-fileupload> tag where you would like to accept file uploads and use the special [coral-fileupload-*] attributes to add functionality to elements within it.

By default, FileUpload will upload files using a POST request. You can set the method attribute to to PUT or PATCH, depending on your use case.

To se the upload URL, set the action attribute.

Drag files here!
Show Markup

                      

Synchronous Usage: Inside of a <form>

The FileUpload component can be nested inside of a <form> and used as a styled file selection button that optionally accepts drag and drop operations.

As usual, add the <coral-fileupload> tag and set the [coral-fileupload-*] attributes on child elements to add upload functionality to them.

When using FileUpload synchonrously, if you need change the HTTP method or action URL of the request, do so on the <form> tag itself, not the <coral-fileupload> tag.

Show Markup

                      

Setting the upload action and method with a button

When using FileUpload asynchronously, the action attribute is used as the upload URL. If you would like to change the upload URL based on which button was clicked, you can do so with the [formaction] and [formmethod] attributes. This works across all browsers when using FileUpload asynchronously.

Because these attributes are part of HTML 5, it will also affect the action of the <form> when used within a <coral-fileupload> element that is a child of a <form> element. Note that browser support for [formaction]/[formmethod] is poor in outdated browsers, so when FileUpload synchonrously in combination with these attributes, you must polyfill this behavior.

Show Markup

            

Coral.FileUpload API

Constructor

JavaScript:

new Coral.FileUpload() or document.createElement('coral-fileupload')

HTML Tag:

<coral-fileupload>

Extends

Sub-components

Static Properties

Coral.FileUpload.method {String}

Enumeration representing HTTP methods that can be used to upload files.

Properties:

Name Type Value Description
POST String POST Send a POST request. Used when creating a resource.
PUT String PUT Send a PUT request. Used when replacing a resource.
PATCH String PATCH Send a PATCH request. Used when partially updating a resource.

Instance Properties

instance.accept {String}

Reflected
MIME types allowed for uploading (proper MIME types, wildcard '*' and file extensions are supported). To specify more than one value, separate the values with a comma (e.g. <input accept="audio/*,video/*,image/*" />.
Default Value:
  • ""
HTML Attribute:
  • accept

instance.action {String}

The URL where the upload request should be sent. When used within a <form> tag to upload synchronously, the action of the form is used. If an element is clicked that has a [coral-fileupload-submit] attribute as well as a [formaction] attribute, the action of the clicked element will be used. Set this property before calling Coral.FileUpload#upload to reset the action set by a click.
Default Value:
  • ""
HTML Attribute:
  • action

instance.async {Boolean}

Reflected
Whether files should be uploaded asynchronously via XHR or synchronously e.g. within a <form> tag. One option excludes the other. Setting a new async value removes all files from the queue.
Default Value:
  • false

instance.autoStart {Boolean}

Reflected
Whether the upload should start immediately after file selection.
Default Value:
  • false
HTML Attribute:
  • autostart

instance.disabled {Boolean}

Reflected
Whether this field is disabled or not.
Inherited From:
Default Value:
  • false
HTML Attribute:
  • disabled

instance.invalid {Boolean}

Reflected
Whether the current value of this field is invalid or not.
Inherited From:
Default Value:
  • false
HTML Attribute:
  • invalid

instance.labelledBy {String}

Reference to a space delimited set of ids for the HTML elements that provide a label for the formField. Implementers should override this method to ensure that the appropriate descendant elements are labelled using the aria-labelledby attribute. This will ensure that the component is properly identified for accessibility purposes. It reflects the aria-labelledby attribute to the DOM.
Inherited From:
Default Value:
  • null
HTML Attribute:
  • labelledby

instance.method {Coral.FileUpload.method}

The HTTP method to use when uploading files asynchronously. When used within a <form> tag to upload synchronously, the method of the form is used. If an element is clicked that has a [coral-fileupload-submit] attribute as well as a [formmethod] attribute, the method of the clicked element will be used. Set this property before calling Coral.FileUpload#upload to reset the method set by a click.
Default Value:
  • Coral.FileUpload.method.POST
HTML Attribute:
  • method

instance.multiple {Boolean}

Reflected
Whether more than one file can be chosen at the same time to upload.
Default Value:
  • false
HTML Attribute:
  • multiple

instance.name {String}

Reflected
Name used to submit the data in a form.
Inherited From:
Default Value:
  • ""
HTML Attribute:
  • name

instance.parameters {Array.<Object>}

Array of additional parameters as key:value to send in addition of files. A parameter must contain a name key:value and optionally a value key:value.
Default Value:
  • []

instance.readOnly {Boolean}

Reflected
Whether this field is readOnly or not.
Inherited From:
Default Value:
  • false
HTML Attribute:
  • readonly

instance.required {Boolean}

Reflected
Whether this field is required or not.
Inherited From:
Default Value:
  • false
HTML Attribute:
  • required

instance.sizeLimit {Number}

File size limit in bytes for one file. The value of 0 indicates unlimited, which is also the default.
Default Value:
  • 0
HTML Attribute:
  • sizelimit

instance.uploadQueue {Array.<Object>}

Readonly
Files waiting impatiently to be uploaded.
Default Value:
  • []

instance.value {String}

This field's current value.
Inherited From:
Default Value:
  • ""
HTML Attribute:
  • value

instance.values {Array.<String>}

The names of the currently selected files. When Coral.FileUpload#multiple is false, this will be an array of length 1.

Methods

instance.abort

Abort upload of a given file or all files in the queue.
Parameters:
Name Type Optional Description
filename String Yes
The filename of the file to abort. If a filename is not provided, all files will be aborted.

instance.clear

Remove a file or all files from the upload queue.
Parameters:
Name Type Optional Description
filename String Yes
The filename of the file to remove. If a filename is not provided, all files will be removed.

instance.get

Get the value of a property.
Parameters:
Name Type Description
property String The name of the property to fetch the value of.
Returns:
Property value. {*}
Inherited From:

instance.hide

Hide this component.
Returns:
this, chainable {Coral.Component}
Inherited From:

instance.off

Remove an event listener.
Parameters:
Name Type Optional Description
eventName String No
The event name to stop listening for.
selector String Yes
The selector that was used for event delegation.
func function No
The function that was passed to on().
useCapture Boolean Yes
Only remove listeners with useCapture set to the value passed in.
Returns:
this, chainable. {Coral.Component}
Inherited From:

instance.on

Add an event listener.
Parameters:
Name Type Optional Default Description
eventName String No
The event name to listen for.
selector String Yes
The selector to use for event delegation.
func function No
The function that will be called when the event is triggered.
useCapture Boolean Yes
false Whether or not to listen during the capturing or bubbling phase.
Returns:
this, chainable. {Coral.Component}
Inherited From:

instance.remove

Non-destructively remove this element. It can be re-added by simply appending it to the document again. It will be garbage collected if there are no more references to it. This is different from using jQuery's remove(), which is destructive in that it removes data and listeners.
Inherited From:

instance.show

Show this component.
Returns:
this, chainable {Coral.Component}
Inherited From:

instance.trigger

Trigger an event.
Parameters:
Name Type Optional Default Description
eventName String No
The event name to trigger.
props Object Yes
Additional properties to make available to handlers as event.detail.
bubbles Boolean Yes
true Set to false to prevent the event from bubbling.
cancelable Boolean Yes
true Set to false to prevent the event from being cancelable.
Returns:
CustomEvent object {CustomEvent}
Inherited From:

instance.upload

Uploads the given filename, or all the files into the queue. It accepts extra parameters that are sent with the file.
Parameters:
Name Type Optional Description
filename String Yes
The name of the file to upload.

Events

change

Triggered when the value has changed. This event is only triggered by user interaction.
Callback Parameters:
Name Type Description
event Object Event object.
Inherited From:

coral-component:attached

Triggered when the component is attached to the DOM.
Callback Parameters:
Name Type Description
event Object Event object.
Inherited From:

coral-component:detached

Triggered when the component is detached to the DOM.
Callback Parameters:
Name Type Description
event Object Event object.
Inherited From:

coral-component:ready

Triggerred when the component has been upgraded and is ready for use.
Callback Parameters:
Name Type Description
event Object Event object.
Inherited From:

coral-fileupload:abort

Triggered when the upload is terminated. Does not trigger in IE9.
Callback Parameters:
Name Type Description
event Object

Event object

Name Type Description
event.detail.action Object The URL the file is being uploaded to.
event.detail.method Coral.FileUpload.method HTTP method used to upload.
event.detail.item Coral.FileUpload.Item FileUpload item.

coral-fileupload:dragenter

Triggered when a file enters a dropzone.
Callback Parameters:
Name Type Description
event Object Event object

coral-fileupload:dragleave

Triggered when a file is dragged out of a dropzone.
Callback Parameters:
Name Type Description
event Object Event object

coral-fileupload:dragover

Triggered when a file is being dragged over a dropzone.
Callback Parameters:
Name Type Description
event Object Event object

coral-fileupload:drop

Triggered when a file is dropped on a dropzone.
Callback Parameters:
Name Type Description
event Object

Event object

Name Type Description
event.detail.item Coral.FileUpload.Item FileUpload item.

coral-fileupload:error

Triggered when the upload fails. Does not trigger in IE9.
Callback Parameters:
Name Type Description
event Object

Event object

Name Type Description
event.detail.action Object The URL the file is being uploaded to.
event.detail.method Coral.FileUpload.method HTTP method used to upload.
event.detail.item Coral.FileUpload.Item FileUpload item.

coral-fileupload:fileadded

Triggered when a file is added to the queue.
Callback Parameters:
Name Type Description
event Object

Event object

Name Type Description
event.detail.item Coral.FileUpload.Item FileUpload item.

coral-fileupload:filemimetyperejected

Triggered when a file is rejected due to its MIME type.
Callback Parameters:
Name Type Description
event Object

Event object

Name Type Description
event.detail.item Coral.FileUpload.Item The rejected FileUpload item.

coral-fileupload:fileremoved

Triggered when a file is removed from the queue.
Callback Parameters:
Name Type Description
event Object

Event object

Name Type Description
event.detail.item Coral.FileUpload.Item FileUpload item.

coral-fileupload:filesizeexceeded

Triggered when a file size exceeds the file size limit.
Callback Parameters:
Name Type Description
event Object

Event object

Name Type Description
event.detail.item Coral.FileUpload.Item The rejected FileUpload item.

coral-fileupload:load

Triggered when the upload has successfully finished. Does not trigger in IE9.
Callback Parameters:
Name Type Description
event Object

Event object

Name Type Description
event.detail.action Object The URL the file is being uploaded to.
event.detail.method Coral.FileUpload.method HTTP method used to upload.
event.detail.item Coral.FileUpload.Item FileUpload item.

coral-fileupload:loadend

Triggered when the upload is stopped.
Callback Parameters:
Name Type Description
event Object

Event object

Name Type Description
event.detail.action Object The URL the file is being uploaded to.
event.detail.method Coral.FileUpload.method HTTP method used to upload.
event.detail.item Coral.FileUpload.Item FileUpload item.

coral-fileupload:loadstart

Triggered when the upload has begun.
Callback Parameters:
Name Type Description
event Object

Event object

Name Type Description
event.detail.action Object The URL the file is being uploaded to.
event.detail.method Coral.FileUpload.method HTTP method used to upload.
event.detail.item Coral.FileUpload.Item FileUpload item.

coral-fileupload:progress

Triggered during upload progress. Does not trigger in IE9.
Callback Parameters:
Name Type Description
event Object

Event object

Name Type Description
event.detail.action Object The URL the file is being uploaded to.
event.detail.method Coral.FileUpload.method HTTP method used to upload.
event.detail.item Coral.FileUpload.Item FileUpload item.
event.detail.lengthComputable Boolean Whether the upload progress can be calculated.
event.detail.loaded Number The upload progress in bytes.
event.detail.total Number The total upload size in bytes.

coral-fileupload:readystatechange

Triggered every time the readyState changes. Does not trigger in IE9.
Callback Parameters:
Name Type Description
event Object

Event object

Name Type Description
event.detail.action Object The URL the file is being uploaded to.
event.detail.method Coral.FileUpload.method HTTP method used to upload.
event.detail.item Coral.FileUpload.Item FileUpload item.

coral-fileupload:timeout

Triggered when the upload reaches a timeout. Does not trigger in IE9.
Callback Parameters:
Name Type Description
event Object

Event object

Name Type Description
event.detail.action Object The URL the file is being uploaded to.
event.detail.method Coral.FileUpload.method HTTP method used to upload.
event.detail.item Coral.FileUpload.Item FileUpload item.

Coral.FileUpload.Item API

Constructor

JavaScript:

new Coral.FileUpload.Item()
Parameters:
Name Type Description
file File|HTMLElement The file element.
useHTML5 Boolean Whether the File API should be used.

Static Properties

Coral.FileUpload.Item.responseType {String}

Response types.

Properties:

Name Type Value Description
TEXT String text String type.
ARRAY_BUFFER String arraybuffer Array buffer type.
BLOB String blob Blob type.
DOCUMENT String document Document type.
JSON String json JavaScript object, parsed from a JSON string returned by the server.

Instance Properties

instance.file {File}

Readonly
The File.

instance.parameters {Array.<Object>}

Array of additional parameters as key:value to be uploaded with the file. A parameter must contain a name key:value and optionally a value key:value.
Default Value:
  • []

instance.readyState {Number}

Readonly
The item xhr readyState property.
Default Value:
  • 0

instance.response {String | ArrayBuffer | Blob | Document}

Readonly
The item xhr responseType property. Depends on Coral.FileUpload.Item#responseType.
Default Value:
  • ""

instance.responseText {String}

Readonly
The item xhr responseText property.
Default Value:
  • ""

instance.responseType {Coral.FileUpload.Item.responseType}

The item xhr responseType property.
Default Value:
  • {Coral.FileUpload.Item.responseType.TEXT}

instance.responseXML {HTMLElement}

Readonly
The item xhr responseXML property.
Default Value:
  • null

instance.status {Number}

Readonly
The item xhr status property.
Default Value:
  • 0

instance.statusText {String}

Readonly
The item xhr statusText property.
Default Value:
  • ""

instance.timeout {Number}

The item xhr timeout property.
Default Value:
  • 0

instance.withCredentials {Boolean}

The item xhr withCredentials property.
Default Value:
  • false