vue-transmit v8.1.4

Vue-Transmit

A Vue.js drag & drop uploader based on Dropzone.js (~22KB, ~6.5KB gzipped). Many thanks to Matias Meno for paving the way with the original Dropzone.js! Check it out for any of your non-vue projects. 🙌

Features

Vue-Transmit is a fork of Dropzone.js that has been completely rewritten in TypeScript/ES6 for Vue.js. Instead of creating a Vue wrapper component that duplicates and proxies all of the methods and event logic between Dropzone and the component, Vue-Transmit implements them directly from the component. This cuts down on library size and offers a much tighter integration.

Vue-Transmit takes an event-based approach to the upload cycle. Instead of passing callbacks to the component via an options object, use the template event binding syntax (<vue-transmit @event="callback" />). All events strictly conform to kebab-casing, including events proxied off native events (e.g. dragover => @drag-over). This is for uniformity and so events can be easily distinguished.

In order to comply with Vue.js reactivity, an object's properties must be defined up front and be configurable. A special File class has been written (VTransmitFile) to register file objects from uploads reactively, since the native File object's properties are read-only. This class also adds useful information not present in the native File object (dimensions, upload stats, etc.).

• HTML 5 file uploads
• Emits upload lifecycle events (accepted, sending, progress, success, etc.)
• Image thumbnail previews
• Support for concurrent uploads
• Completely written in Vue.js—no wrapper components
• Scoped slots allow for fully customizable styling
• Written in modern TypeScript/ES6 with modules

* Note: this library uses some built-ins (Array.from) that require a polyfill. All other ESNext language features (arrow fns, for of, etc.) are transpiled with babel.

Installation

npm install vue-transmit

Builds

The default build for ESM loaders like webpack is indicated in the module fields of the package. For most setups, importing the lib would like the following:

// ESM
import VueTransmit from "vue-transmit";
// Common.js
const VueTransmit = require("vue-transmit");
// Browser
window.VueTransmit;

// Installation
Vue.use(VueTransmit);

Props: <vue-transmit>

Events

Slots

Default ($slots.default)

The default slot should contain your markup for getting an upload started. This could be a file uploader button and/or a dropzone.

Files (Scoped, $slots.files)

This slot receives a number of props:

interface FilesSlotProps {
  files: VTransmitFile[];
  acceptedFiles: VTransmitFile[];
  rejectedFiles: VTransmitFile[];
  addedFiles: VTransmitFile[];
  queuedFiles: VTransmitFile[];
  uploadingFiles: VTransmitFile[];
  activeFiles: VTransmitFile[];
  isUploading: Boolean;
}

VTransmitFile

{
  "_nativeFile": {},
  "id": "v-transmit-file-1",
  "accepted": true,
  "lastModified": 1478117443000,
  "lastModifiedDate": "2016-11-02T20:10:43.000Z",
  "name": "cosmo.jpg",
  "processing": true,
  "size": 142776,
  "status": "success",
  "type": "image/jpeg",
  "upload": {
    "bytesSent": 142776,
    "progress": 100,
    "speed": {
      "kbps": 10.06,
      "mbps": 0.01
    },
    "start": 1503273157993,
    "end": 1503273158029,
    "time": 0.036,
    "total": 142776
  },
  "webkitRelativePath": "",
  "width": 700,
  "height": 700,
  "xhr": {},
  "dataUrl":
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHgAAAB4CAYAAAA5ZDbSAAAgAElEQVR4XlS9B7RmZ3UluG/="
}

Usage

If you have PHP installed on your machine, you can clone this repo and open up a working test app by running:

npm test

Now navigate to http://localhost:3030/.

<template>
  <main id="root" class="mt-5">
    <div class="container">
      <div class="row">
        <header class="col-12 text-center">
          <h1 class="mb-5"><code>&lt;vue-transmit&gt;</code></h1>
        </header>
        <vue-transmit class="col-12"
                      tag="section"
                      v-bind="options"
                      upload-area-classes="bg-faded"
                      ref="uploader">
          <div class="d-flex align-items-center justify-content-center w-100"
                style="height:50vh; border-radius: 1rem;">
            <button class="btn btn-primary"
                    @click="triggerBrowse">Upload Files</button>
          </div>
          <!-- Scoped slot -->
          <template slot="files" scope="props">
            <div v-for="(file, i) in props.files" :key="file.id" :class="{'mt-5': i === 0}">
              <div class="media">
                <img :src="file.dataUrl" class="img-fluid d-flex mr-3">
                <div class="media-body">
                  <h3>{{ file.name }}</h3>
                  <div class="progress" style="width: 50vw;">
                    <div class="progress-bar bg-success"
                        :style="{width: file.upload.progress + '%'}"></div>
                  </div>
                  <pre>{{ file | json }} </pre>
                </div>
              </div>
            </div>
          </template>
        </vue-transmit>
      </div>
    </div>
  </main>
</template>

<script>
  Vue.use(VueTransmit)
  window.app = new Vue({
    el: '#root',
    data: {
      options: {
        acceptedFileTypes: ['image/*'],
        url: './upload.php',
        clickable: false
      }
    },
    methods: {
      triggerBrowse() {
        this.$refs.uploader.triggerBrowseFiles()
      },
    },
    filters: {
      json(value) {
        return JSON.stringify(value, null, 2)
      }
    }
  })
</script>

Lifecycle

The upload process has many stages, each with different possible outcomes. Here is an overview of the lifecycle of an upload with Vue Transmit:

• Trigger event
  • input on change: value of input.files is read and passed to vm.addFile
  • target on drop: value of event.dataTransfer["files" || "items"] is read/traversed and passed to vm.addFile
• Add File
  • instantiate VTransmitFile from native file object (for reactivity & extra info)
  • status added
  • pushed onto vm.files
  • thumbnail is enqueued
• Accept File
  • check size, type, upload limit
  • invoke accept function for consumer validation
  • accept or reject complete
  • if autoQueue, enqueue file
• Enqueue file
  • check that file status is added & has been accepted
  • status = queued
  • if autoProcessQueue, invoke processQueue async (like node setImmediate)
• Process queue
  • check number of uploading files against upload limit
  • invoke processFiles with max amount of queued files options allow
• Process files
  • do upload
• Progress updates
• Complete upload
  • status = success || error
  • process queue to handle buffered files