Coral.FileUpload

Current Version: 4.0.8
Note:Any Coral CSS classes and attributes not explicitly mentioned in the public documentation are private and subject to change. Their direct use is not recommended and at high risk of breaking after subsequent updates of CoralUI library. For technical details of how to use Coral safely, please refer to the CoralUI Architecture.
Github: @coralui/coralui-component-fileupload

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

Forms

Vertical Layout

Show Markup 
<form class="coral-Form coral-Form--vertical u-columnSmall">
  <section class="coral-Form-fieldset">
    <div class="coral-Form-fieldwrapper">
      <label id="label-vertical-0" class="coral-Form-fieldlabel">Label</label>
      <coral-fileupload class="coral-Form-field" name="name" labelledby="label-vertical-0" action="/upload">
        <button is="coral-button" coral-fileupload-select icon="upload">Upload Files</button>
      </coral-fileupload action="/upload">
    </div>
  
    <div class="coral-Form-fieldwrapper">
      <label id="label-vertical-1" class="coral-Form-fieldlabel">Required</label>
      <coral-fileupload class="coral-Form-field" name="name" labelledby="label-vertical-1" action="/upload" required>
        <button is="coral-button" coral-fileupload-select icon="upload">Upload Files</button>
      </coral-fileupload action="/upload">
      <coral-icon class="coral-Form-fieldinfo" icon="infoCircle" size="S" id="coral-form-vertical-fileupload-fieldinfo"></coral-icon>
      <coral-tooltip variant="info" placement="right" target="#coral-form-vertical-fileupload-fieldinfo">Required Information</coral-tooltip>
    </div>
  
    <div class="coral-Form-fieldwrapper">
      <label id="label-vertical-2" class="coral-Form-fieldlabel">Invalid</label>
      <coral-fileupload class="coral-Form-field" name="name" labelledby="label-vertical-2" action="/upload" invalid>
        <button is="coral-button" coral-fileupload-select icon="upload">Upload Files</button>
      </coral-fileupload action="/upload">
      <coral-icon class="coral-Form-fielderror" icon="infoCircle" size="S" id="coral-form-vertical-fileupload-fielderror"></coral-icon>
      <coral-tooltip variant="error" placement="right" target="#coral-form-vertical-fileupload-fielderror">Error Message</coral-tooltip>
    </div>
  </section>
</form>

Aligned Layout

Show Markup 
<form class="coral-Form coral-Form--aligned u-columnLarge">
  <section class="coral-Form-fieldset">
    <div class="coral-Form-fieldwrapper">
      <label id="label-aligned-0" class="coral-Form-fieldlabel">Label</label>
      <coral-fileupload class="coral-Form-field" name="name" labelledby="label-aligned-0" action="/upload">
        <button is="coral-button" coral-fileupload-select icon="upload">Upload Files</button>
      </coral-fileupload action="/upload">
    </div>
  
    <div class="coral-Form-fieldwrapper">
      <label id="label-aligned-1" class="coral-Form-fieldlabel">Required</label>
      <coral-fileupload class="coral-Form-field" name="name" labelledby="label-aligned-1" required action="/upload">
        <button is="coral-button" coral-fileupload-select icon="upload">Upload Files</button>
      </coral-fileupload action="/upload">
      <coral-icon class="coral-Form-fieldinfo" icon="infoCircle" size="S" id="coral-form-aligned-fileupload-fieldinfo"></coral-icon>
      <coral-tooltip variant="info" placement="right" target="#coral-form-aligned-fileupload-fieldinfo">Required Information</coral-tooltip>
    </div>
  
    <div class="coral-Form-fieldwrapper">
      <label id="label-aligned-2" class="coral-Form-fieldlabel">Invalid</label>
      <coral-fileupload class="coral-Form-field" name="name" labelledby="label-aligned-2" invalid action="/upload">
        <button is="coral-button" coral-fileupload-select icon="upload">Upload Files</button>
      </coral-fileupload action="/upload">
      <coral-icon class="coral-Form-fielderror" icon="infoCircle" size="S" id="coral-form-aligned-fileupload-fielderror"></coral-icon>
      <coral-tooltip variant="error" placement="right" target="#coral-form-aligned-fileupload-fielderror">Error Message</coral-tooltip>
    </div>
  </section>
</form>

Usage

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.

Usage: In place of a <form>

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

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.

The async attribute can be used to submit the form files asynchronously. In this case, the data is submitted via a XMLHttpRequest. By default, asynchronous upload is disabled.

To set the upload URL, set the action attribute.

Drag files here!
Show Markup 
<coral-fileupload method="put" action="/account" class="coral-Form-field">
  <button type="button" coral-fileupload-select is="coral-button" variant="secondary">Select file...</button>
  <div coral-fileupload-dropzone> Drag files here!</div>
</coral-fileupload>

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 synchronously, if you need to change the HTTP method or action URL of the request, do so on the <form> tag itself, not the <coral-fileupload> tag.

Show Markup 
<form class="coral-Form coral-Form--aligned" method="put" action="/acccount">
  <section class="coral-Form-fieldset">
    <label class="coral-Form-fieldlabel" for="name">Name</label>
    <input is="coral-textfield" class="coral-Form-field" type="text" id="name" placeholder="Your Name">
  
    <label class="coral-Form-fieldlabel" for="email">E-mail</label>
    <input is="coral-textfield" class="coral-Form-field" type="email" id="email" placeholder="your@name.com">
  
    <label class="coral-Form-fieldlabel">Profile Picture</label>
    <coral-fileupload class="coral-Form-field">
      <button type="button" coral-fileupload-select coral-fileupload-dropzone is="coral-button" variant="secondary">Browse...</button>
    </coral-fileupload>
  
    <label class="coral-Form-fieldlabel">&nbsp;</label>
    <button class="coral-Form-field" type="submit" is="coral-button" variant="primary">Submit</button>
  </section>
</form>

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 action="/files" multiple>
  <button coral-fileupload-select is="coral-button">Browse...</button>
  <button is="coral-button" variant="primary" coral-fileupload-submit formaction="/media">Upload to /media</button>
  <button is="coral-button" variant="primary" coral-fileupload-submit >Upload to /files</button>
</coral-fileupload>

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.hidden {Boolean}

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

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. Indicating that the user cannot modify the value of the control. This is ignored for checkbox, radio or fileupload.
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
 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.
Inherited From:

instance.set

Set a single property.
Parameters:
Name Type Description
property String The name of the property to set.
value * The value to set the property to.
silent Boolean If true, events should not be triggered as a result of this set.
Returns:
this, chainable. {Coral.Component}
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
 Set to false to prevent the event from bubbling.
cancelable Boolean Yes
 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:
Deprecated:
  • since 1.14.0, use MutationObserver instead.

    coral-component:detached

    Triggered when the component is detached to the DOM.
    Callback Parameters:
    Name Type Description
    event Object Event object.
    Inherited From:
    Deprecated:
    • since 1.14.0, use MutationObserver instead.

      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:
      Deprecated:
      • since 1.9.0, use Coral.commons.ready() instead.

        coral-fileupload:abort

        Triggered when the upload is terminated.
        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.
        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. Event should not be relied upon as a sufficient security measure - server side validation is still necessary from a security perspective.
        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.
        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.
        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.
        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.
        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.

        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