← Back


Polymer-based web component for D2L file uploader




[ This description is mirrored from at on 2019-05-10 ]


Published on Bower version Build status

Polymer component for uploading files with drag and drop capability. This component does not perform the actual uploading work, it simply provides visual cues and exposes an event when files have been uploaded.

screenshot of file uploader

For further information on this and other components, refer to The Brightspace UI Guide.


d2l-file-uploader can be installed from Bower:

bower install d2l-file-uploader


Include the webcomponents.js "lite" polyfill (for browsers who don't natively support web components), then import d2l-file-uploader.html:

    <script src="../webcomponentsjs/webcomponents-lite.js"></script>
    <link rel="import" href="../d2l-file-uploader/d2l-file-uploader.html">

Basic Usage with Accessible Label

It's important to always provide an accessible label which describes the purpose of the uploader using the label attribute. The label will be hidden visually but associated with the upload input for those using assistive technologies such as a screen reader.

<d2l-file-uploader label="profile picture"></d2l-file-uploader>

Multi-file Uploads

To allow for multiple files to be uploaded, add the multiple attribute:

<d2l-file-uploader multiple ...></d2l-file-uploader>


The file uploader will automatically render using the language found on the HTML element -- i.e. <html lang="fr">. If the language attribute is not present or isn't supported, the uploader will render in English.

screenshot of file uploader localized

Feedback Messages

If you encounter a scenario where you'd like to display feedback about the uploaded file(s) -- like a warning or an error -- use the feedback and feedback-type attributes.

The feedback-type defaults to "warning":

    feedback="Sorry, we cannot upload files larger than 1GB.">

screenshot of file uploader in warning state

But feedback-type can also be set to "error":

    feedback="An error occurred occurred processing the upload."

screenshot of file uploader in error state

Feedback Changed Event

To listen for when feedback changes within the uploader, register for the feedback-changed event.

Vanilla JavaScript:

<d2l-file-uploader id="my-uploader" ...></d2l-file-uploader>
    .addEventListener('feedback-changed', function(evt) {
        var feedbackMessage = evt.detail.value;

From within another Polymer element you can use Polymer's annotated event listeners:

<dom-module id="my-element">
        <d2l-file-uploader on-feedback-changed="handleFeedback"></d2l-file-uploader>

Handling Uploaded Files

When the user uploads one or more files, a d2l-file-uploader-files-added event is fired. To listen for this event, wire up an event listener to the <d2l-file-uploader> element. The listener will be passed an event with an array of File objects from the File API.

Vanilla JavaScript:

<d2l-file-uploader id="my-uploader" ...></d2l-file-uploader>
    .addEventListener('d2l-file-uploader-files-added', function(evt) {
        var files = evt.detail.files;

From within another Polymer element you can use Polymer's annotated event listeners:

<dom-module id="my-element">
        <d2l-file-uploader on-d2l-file-uploader-files-added="handleFileAdded"></d2l-file-uploader>

Developing, Testing and Contributing

After cloning the repo, run npm install to install dependencies.

If you don't have it already, install the Polymer CLI globally:

npm install -g polymer-cli

To start a local web server that hosts the demo page and tests:

polymer serve

To lint (eslint and Polymer lint):

npm run lint

To run unit tests locally using Polymer test:

polymer test --skip-plugin sauce

To lint AND run local unit tests:

npm test


Commits and PR merges to master will automatically do a minor version bump which will:

  • Update the version in package.json
  • Add a tag matching the new version
  • Create a github release matching the new version

By using either [increment major] or [increment patch] notation inside your merge message, you can overwrite the default version upgrade of minor to the position of your choice.


(Loading compatibility data...)

Was this helpful? Need more help?
Leave a comment or a question below. You can also join the chat on Discord or ask questions on StackOverflow.



  • polymer#^1.9.1
  • d2l-colors#^2.2.3
  • app-localize-behavior#PolymerElements/app-localize-behavior#^1.0.2
  • d2l-typography#^5.4.0
Apache License 2.0


Polymer 1.0+
Polymer 2.0+ in 0.0.21
Browser Independent

Vaadin Add-on Directory

Find open-source widgets, add-ons, themes, and integrations for your Vaadin application. Vaadin Add-on Directory
The channel for finding, promoting, and distributing Vaadin add-ons.