Uploader     

Quasar supplies a way for you to upload files through QUploader component.

Works well with QField for additional functionality such as a helper, error message placeholder and many others.

Uploader Screenshot 2

Installation

Edit /quasar.conf.js:

framework: {
  components: ['QUploader']
}

Basic Usage

<q-uploader :url="url" />

Vue Properties

Vue PropertyTypeDescription
urlString(Required) URL or path to the server which handles the upload
nameStringName of the file, if it should be different than the file’s name.
headersObjectSpecify what headers need to be added to the XHR request
url-factoryFunctionFunction (with file object received as parameter) which returns a Promise that resolves to a URL.
upload-factoryFunction(v0.17+) Function defining a custom upload method which returns a Promise that resolves with a file. Check section below.
no-content-typeBoolean(v0.17+) Avoid setting Content-Type header when uploading.
with-credentialsBoolean(v0.17+) Sets xhr.withCredentials to true (doesn’t apply when using upload-factory).
methodStringHTTP method to use (POST/PUT). Defaults to POST.
filterFunction(v0.17+) Function defining a custom filter method which returns a list of filtered files. Check section below.
extensionsStringExtensions to allow for uploading. Example: '.gif,.jpg,.jpeg,.png'
multipleBooleanAllow multiple file uploads
hide-upload-buttonBooleanHides the Upload button. You can then trigger it manually by calling upload() on the Vue ref
hide-upload-progressBooleanHides the upload progress. Useful when you want some other means of signaling upload progress to the user.
additional-fieldsArrayAdditional fields to send along the upload request. Useful for authentication and so on. Array of Objects containing name and value props.
no-thumbnailsBooleanDon’t display thumbnails when files are images.
auto-expandBooleanAuto-expand the list of files when some are added to the queue.
expand-styleString/Array/ObjectStyle of the expanded file list container.
expand-classString/Array/ObjectClasses of the expanded file list container.
send-rawBooleanDon’t use multipart/form-data and send the file content inside the request body. If using this approach you will need to specify the correct Content-Type header. Defaults to false.
readonlyBooleanIf set to true, Uploader is displayed as read-only.
clearableBooleanIf set to true, the component offers the user an actionable icon to remove the current selection.

Common input frame properties:

PropertyTypeDescription
prefixStringA text that should be shown before the textfield.
suffixStringA text that should be shown after the textfield.
float-labelStringA text label that will “float” up above the input field, once the input field gets focus.
stack-labelStringA text label that will be shown above the input field and is static.
colorStringOne from Quasar Color Palette.
invertedBooleanInverted mode. Color is applied to background instead.
inverted-lightBooleanInverted mode with a light color. Color is applied to background instead.
darkBooleanIs QUploader rendered on a dark background?
hide-underlineBooleanHides the bottom border.
alignStringOne of ‘left’, ‘center’ or ‘right’ which determines the text align within textfield.
disableBooleanIf set to true, Uploader is disabled and the user cannot change anything.
errorBooleanIf set to true, the input fields colors are changed to show there is an error.
warningBooleanSame as error, the input field color is changed to show there is a warning.
beforeArray of ObjectsIcon buttons on left side of input frame. Read below more details.
afterArray of ObjectsIcon buttons on right side of input frame. Read below more details.
no-parent-fieldBooleanAvoid trying to connect to a parent QField.

Upload Factory

Sometimes you need to define your own upload method. You can do this through upload-factory parameter, as below:

<template>
  <q-uploader
    url=""
    :upload-factory="uploadFile"
  />
</template>

<script>
export default {
  methods: {
    uploadFile (file, updateProgress) {
      // "file" is an Object containing file's props, including content

      // for updating progress (as 0-1 floating number), we need to call:
      // updateProgress (bytesTransferred / totalBytes)

      // we need to return a Promise
      // (resolves when upload is done, rejects when there's an error)
    }
  }
}
</script>

Filter files

Sometimes you need to filter files before upload. You can do this through filter parameter.
Below an example with max file size check:

<template>
  <q-uploader
    url=""
    :filter="filterFiles"
  />
</template>

<script>
export default {
  methods: {
    filterFiles (files) {
      const MAX_FILE_SIZE = 3 * 1024 * 1024 /* =3M */
      // returns an Array containing allowed files
      return files.filter((file) => {
        return file.size <= MAX_FILE_SIZE
      })
    }
  }
}
</script>

Icon buttons

This section refers to before and after properties which can add additional buttons as icons to the textfield. Here is the structure of the two properties:

{
  // required icon
  icon: String,
  // required function to call when
  // icon is clicked/tapped
  handler: Function,

  // Optional. Show icon button
  // if model has a value
  content: Boolean,

  // Optional. Show icon button
  // if textfield is marked with error
  error: Boolean
}

Examples:

<!--
  Show an icon button (with 'warning' as icon)
-->
<q-uploader
  :url="url"
  :after="[
    {
      icon: 'warning',
      handler () {
        // do something...
      }
    }
  ]"
/>

Vue Methods

Vue MethodDescription
upload()Start file(s) upload.
abort()Abort uploading file(s).
reset()Reset uploader state.

Vue Events

Vue EventDescription
@add(files)Triggered when file is picked for upload
@remove:abort(file)Triggered when file is removed from upload queue while uploading.
@remove:cancel(file)Triggered when file is removed from upload queue before uploading.
@remove:done(file)Triggered when file is removed from upload list after it has been uploaded.
@uploaded(file, xhr)Triggered individually for each file that has just been uploaded
@fail(file, xhr)Triggered individually for each file that has encountered error while uploading
@startTriggered when upload has started
@finishTriggered when upload of file(s) has ended (with success or failure)

Examples

AWS S3 - Uploading Using Pre-Signed URLs

<!--
 x-amz-acl and content-type headers must match the ACL and ContentType
 specified when generating the signed url.
-->
<q-uploader
  url=""
  method="PUT"
  :headers="{ 'x-amz-acl': <acl>, 'content-type': <file-type> }"
  :url-factory="getSignedUrl"
  :send-raw="true"
/>
async getSignedUrl (file) {
  const contentType = file.type // To send the correct Content-Type
  const fileName = file.name // If you want to use this value to calculate the S3 Key.
  const response = await api.getSignedUrl({ fileName, contentType }) // Your api call to a sever that calculates the signed url.
  return response.data.url
}
Knob Card
Last updated: Sat May 25 2019
Caught a mistake or want to contribute to the documentation? Suggest an edit on GitHub