Introduction
Vue clip is a minimalistic and hackable file uploader for VueJs. I wrote this plugin due to the absence of well written file uploaders with fine-grained controls.
Features
- Written in vanilla Javascript.
- Weighs 17.9KB ( Minified and Gzip ), 57KB ( Minified ).
- Hackable to the core with custom events.
Setup
You can make use of module by installing it from npm
or directly using it from CDN.
Npm
npm i --save vue-clip
Vue
Globally
Also, you can reference the script file via CDN which will add a global component called vue-clip
to the Vue instance.
Basic Usage
Click or Drag and Drop files here upload {{ file.name }} {{ file.status }}
Configuration Options
Option | Possible Values | Description |
---|---|---|
url | String, Function | Url to be used for uploading files. This can be a string or a function ( in case your URL is dynamic ) |
method | String, Function | Http method to be used. Defaults to post . |
parallelUploads | Number | Number of files to be uploaded in parallel. |
maxFilesize | Number, Object | The file size in MB to be allowed. Also, you can pass an object with limit and error message . |
paramName | String | Param name to be used for uploading file(s). Defaults to file . |
uploadMultiple | Boolean | Whether or not to upload multiple files. |
headers | Object | Http headers to be sent along each request. |
maxFiles | Number, Object | a maximum number of files to be uploaded. You can also pass an object with limit and error message . |
acceptedFiles | Array, Object | File types to be accepted. ['image/*', 'application/pdf'] . |
accept | Function | A custom function to be used for validating each file upload. This method receives a done callback. In the case of any errors, you must call done with a single error argument. |
maxFilesize
The maxFilesize
option defines the size of the file to be checked for when uploading files.
maxFilesize: 1 // 1mb // or maxFilesize: limit: 1 message: '{{ filesize }} is greater than the {{ maxFilesize }}'
maxFiles
The maxFiles
option defines the maximum number of files to be uploaded.
maxFiles: 5 // or maxFiles: limit: 5 message: 'You can only upload a max of 5 files'
acceptedFiles
The mime types of files to be accepted.
acceptedFiles: 'image/*' 'application/pdf' // or acceptedFiles: extensions: 'image/*' message: 'You are uploading an invalid file'
accept
The accept
is a low-level method to run manual validations and return a formatted error string ( in the case of error).
{ if filesize > 1024 * 1024 return }
Dragging
The most common requirement is to know when a user starts
and stops
dragging a file so that you can add some visual feedback to the UI. The easiest way is to make use of Scoped slots.
Click or Drag and Drop files here upload
Events
You can make use of vue-clip
without writing any javascript code, but if you want low-level control over the upload behavior, consider listening to special events.
onInit(uploader)
Called every time the vue-clip
is initiated and binds to DOM.
onAddedFile(file)
This event is invoked every time a new file gets uploaded. You can listen for this event, you want to have access to each file object within your own parent component.
onRemovedFile(file)
This event is invoked every time the file has been removed. This is the nice place to make a request to your server for deleting the file.
onSending(file, XHR, formData)
This event is emitted before making the upload HTTP request. So this is the time to modify the HTTP request and send some custom attributes.
onComplete(file, status, xhr)
This event is called when a file has been processed. It includes error, success both. 3rd argument
will be the xhr response, if the error is returned from the server when uploading the file.
onDragEnter
This event is invoked as soon as the user starts dragging the file.
onDragLeave
This event is invoked when the user stops dragging the file.
onDrop
This event is invoked when the user drops a file on the vue-clip area.
onTotalProgress(progress, totalBytes, bytesSent)
This event returns the total upload progress for all the files. Think of it as the global progress indicator for multiple files uploaded together.
onQueueComplete
The event is called when all files in the queue have been uploaded to the server.
onMaxFiles
The event is called when maxFiles upload limit has been reached. This event will be fired n times
for each file exceeding the limit. For example
- maxFiles - 3
- filesUploaded - 5
- eventCalled - 2 times with file instance
File Attributes
The file instance sent along events has following attributes.
Attribute | Type | Description |
---|---|---|
name | String | The client name of the file |
status String | String | The file status, which can be success , error , queued , added . |
width | Number | The file width. Only for images. |
height | Number | The file height. Only for images. |
bytesSent | Number | The total bytes sent to the server so far. |
progress | Number | Total upload progress. |
total | Number | The total number of bytes to be sent to the server. |
type | String | The file mime-type. |
size | Number | The file size on user disk. |
dataUrl | String | File base64 data URL to be used for displaying images preview. |
xhrResponse | Object | Server xhrResponse. Only contains response , responseText and statusCode |
errorMessage | String | Error message when processing a file. If the error is returned from the server, it will be the value of XHR error. Also can be client errors for maxSize etc. |
customAttributes | Object | Each file needs some custom attributes, for example server id to be used for deleting the files. |
Adding/Accessing Custom Attributes
file // access idfilecustomAttributesid
Browser Support
- Chrome 7+
- Firefox 4+
- IE 10+
- Opera 12+
- Safari 6+
Things to consider
Make sure you add class dz-message
to the uploader action wrapped inside clip-uploader-action
slot. This makes your entire action body clickable. There are ways to get around it, but I wanted to keep the API transparent, instead of adding a bunch of DOM elements behind the scenes.
Click or Drag and Drop files here upload