Description

Component library to create a HTML5-compliant drag'n'drop zone for files.

Some of WUI Dropzone's highlights are:

• Extensive drop zone features
• Image thumbnail previews
• Progress Bars
• Multiple files and synchronous uploads
• Support for large files
• Chunked uploads (single files can be uploaded as chunks in multiple HTTP requests)
• Custom layouts by provided slots
• Browser image resizing (resize the images before you upload them to your server)
• Well tested

Usage

<template>
  <wui-dropzone url="/url/for/upload" />
</template>

<!-- wui-dropzone.vue -->

If you want to access file contents you have to use the FileReader API:

<template>
  <wui-dropzone url="/url/for/upload" @drop="onDrop" />
</template>

<script>
  export default {
    methods: {
      onDrop(acceptedFiles) {
        acceptedFiles.forEach((file) => {
          const reader = new FileReader();

          reader.onabort = () => console.log("file reading was aborted");
          reader.onerror = () => console.log("file reading has failed");
          reader.onload = () => {
            // Do whatever you want with the file contents
            const binaryStr = reader.result;
            console.log(binaryStr);
          };
          reader.readAsArrayBuffer(file);
        });
      },
    },
  };
</script>

<!-- wui-dropzone-basic-drop-event.vue -->

Custom Dropzones

You can also create your own drop zone by using the scoped default slot. It provides four getters which just binds the necessary handlers to create a drag 'n' drop zone. Use the getRootProps() and getRootListeners() fn's to get the props and events required for drag 'n' drop and use them on any element. For click and keydown behavior, use the getInputProps() and getInputListeners() fn's and use the returned props and events on an <input>.

Furthermore, the functions supports folder drag 'n' drop by default. See file-selector for more info about supported browsers.

The two root getters can be applied to whatever element you want, whereas the two input getters must be applied to an <input>:

<template>
  <wui-dropzone>
    <template
      #default="{ getRootProps, getRootListeners, getInputProps, getInputListeners }"
    >
      <div v-bind="getRootProps()" v-on="getRootListeners()">
        <input v-bind="getInputProps()" v-on="getInputListeners()" />
      </div>
    </template>
  </wui-dropzone>
</template>

<script>
  import { mixinDropzone } from "./helpers/mixin-dropzone";

  export default {
    mixins: [mixinDropzone],
  };
</script>

<!-- wui-dropzone-custom.vue -->

Note that whatever other props or events you want to add to the element where the props from getRootProps() or getRootListeners() are set, you should always pass them through that function rather than applying them on the element itself. This is in order to avoid your props and events being overridden (or overriding the props and events returned by getRootProps() / getRootListeners()):

<div
  v-bind="getRootProps({
    class: 'my-dropzone',
    role: 'button',
    'aria-label': 'drag and drop area',
    ...
  })"
  v-on="getRootListeners({ click: event => console.log(event) })"
/>

In the example above, the provided click handler will be invoked before the internal one, therefore, internal callbacks can be prevented by simply using stopPropagation.

Important: if you omit rendering an <input> and/or binding the props and events from getInputProps() and getInputListeners(), opening a file dialog will not be possible.

Caveats

File Dialog Cancel Callback Event

The file-dialog-cancel event is unstable in most browsers, meaning, there's a good chance of it being triggered even though you have selected files.

We rely on using a timeout of 300ms after the window is focused (the window onfocus event is triggered when the file select dialog is closed) to check if any files were selected and trigger file-dialog-cancel if none were selected.

As one can imagine, this doesn't really work if there's a lot of files or large files as by the time we trigger the check, the browser is still processing the files and no onchange events are triggered yet on the input.

Fortunately, there's the File System Access API, which is currently a working draft and some browsers support it see browser compatibility), that provides a reliable way to prompt the user for file selection and capture cancellation.

Also keep in mind that the FS access API can only be used in secure contexts.

NOTE You can disable using the FS access API by setting the useFsAccessApi prop to false.

Supported Browsers

We use browserslist config to state the browser support for this lib, so check it out on browserslist.dev.

Need image editing?

To create a modern image editing experience you can use Pintura Image Editor. Pintura supports crop aspect ratios, resizing, rotating, cropping, annotating, filtering, and much more.

Compact Mode

The drop zone can be rendered in a collapsed layout if the compact property is set to true. The file list can also be rendered in a collapsed layout if compactFileList is set to true.

<template>
  <wui-dropzone compact compact-file-list />
</template>

<!-- wui-dropzone-compact.vue -->

Event Propagation

If you'd like to selectively turn off the default dropzone behavior for click, use the noClick property:

<template>
  <wui-dropzone url="/url/for/upload" no-click />
</template>

<!-- wui-dropzone-no-click.vue -->

If you'd like to selectively turn off the default dropzone behavior for keyDown, focus and blur, use the noKeyboard property:

<template>
  <wui-dropzone url="/url/for/upload" no-keyboard>
    <template #info">
      <p class="text-center">Dropzone without keyboard events</p>
      <em class="text-center">(SPACE/ENTER and focus events are disabled)</em>
    </template>
  </wui-dropzone>
</template>

<!-- wui-dropzone-no-keyboard.vue -->

If you'd like to selectively turn off the default dropzone behavior for drag events, use the noDrag property:

<template>
  <wui-dropzone url="/url/for/upload" no-drag>
    <template #info">
      <p class="text-center">Dropzone with no drag events</p>
      <em class="text-center">(Drag 'n' drop is disabled)</em>
    </template>
  </wui-dropzone>
</template>

<!-- wui-dropzone-no-drag.vue -->

Keep in mind that if you provide your own callback handlers as well and use event.stopPropagation(), it will prevent the default dropzone behavior:

<template>
  <wui-dropzone url="/url/for/upload" @drop="onDrop">
    <template #info">
      <p class="text-center">Dropzone with no drag events</p>
      <em class="text-center">(Drag 'n' drop is disabled)</em>
    </template>
  </wui-dropzone>
</template>

<script>
  export default {
    methods: {
      onDrop(acceptedFiles, rejectedFiles, event) {
        event.stopPropagation();
      },
    },
  };
</script>

<!-- wui-dropzone-events-stop-propagation.vue -->

Accepting specific file types

By providing accept prop you can make the dropzone accept specific file types and reject the others.

The value must be an object with a common MIME type as keys and an array of file extensions as values (similar to showOpenFilePicker's types accept option).

accept: {
  'image/png': ['.png'],
  'text/html': ['.html', '.htm'],
}

For more information see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input.

<template>
  <wui-dropzone
    :accept="{
      'image/jpeg': [],
      'image/png': []
    }"
  >
    <template #info">
      <p class="text-center">Drag 'n' drop some files here, or click to select files</p>
      <em class="text-center">(Only *.jpeg and *.png images will be accepted)</em>
    </template>
  </wui-dropzone>
</template>

<!-- wui-dropzone-accept.vue -->

Browser limitations

Because of HTML5 File API differences across different browsers during the drag, Dropzone might not be able to detect whether the files are accepted or rejected in Safari nor IE.

Furthermore, at this moment it's not possible to read file names (and thus, file extensions) during the drag operation. For that reason, if you want to react on different file types during the drag operation, you have to use mime types and not extensions! For example, the following example won't work even in Chrome:

<template>
  <wui-dropzone :accept="{ 'image/jpeg': ['.jpeg', '.png'] }">
    <template #info={ isDragActive, isDragAccept, isDragReject, }">
      <p v-if="isDragAccept" class="text-center">All files will be accepted</p>
      <p v-if="isDragReject" class="text-center">Some files will be rejected</p>
      <p v-if="!isDragActive" class="text-center">Drop some files here ...</p>
    </template>
  </wui-dropzone>
</template>

<!-- wui-dropzone-accept-not-working.vue -->

but this one will:

<template>
  <wui-dropzone :accept="{ 'image/*': ['.jpeg', '.png'] }">
    <template #info={ isDragActive, isDragAccept, isDragReject, }">
      <p v-if="isDragAccept" class="text-center">All files will be accepted</p>
      <p v-if="isDragReject" class="text-center">Some files will be rejected</p>
      <p v-if="!isDragActive" class="text-center">Drop some files here ...</p>
    </template>
  </wui-dropzone>
</template>

<!-- wui-dropzone-accept-working.vue -->

Notes

Mime type determination is not reliable across platforms. CSV files, for example, are reported as text/plain under macOS but as application/vnd.ms-excel under Windows. In some cases there might not be a mime type set at all.

Accepting specific number of files

By providing maxFiles prop you can limit how many files the dropzone accepts.

Note that this prop is enabled when the multiple prop is enabled. The default value for this prop is 0, which means there's no limitation to how many files are accepted.

<template>
  <wui-dropzone :max-files="2" />
</template>

<!-- wui-dropzone-max-files.vue -->

Custom validation

By providing validator prop you can specify custom validation for files.

The value must be a function that accepts File object and returns null if file should be accepted or error object/array of error objects if file should be rejected.

<template>
  <wui-dropzone :validator="nameLengthValidator" />
</template>

<script>
  export default {
    data() {
      return {
        maxLength: 20,
      };
    },

    methods: {
      nameLengthValidator(file) {
        if (file.file.name.length > this.maxLength) {
          return {
            code: "name-too-large",
            message: `Name is larger than ${this.maxLength} characters`,
          };
        }

        return null;
      },
    },
  };
</script>

<!-- wui-dropzone-validator.vue -->

Opening File Dialog Programmatically

You can programmatically invoke the default OS file prompt; just use the open instance method provided by most of the scoped slots (e. h. #info).

Note that for security reasons most browsers require popups and dialogues to originate from a direct user interaction (i.e. click).

If you are calling open() asynchronously, there’s a good chance it’s going to be blocked by the browser. So if you are calling open() asynchronously, be sure there is no more than 1000ms delay between user interaction and open() call.

Due to the lack of official docs on this (at least we haven’t found any. If you know one, please let us know), there is no guarantee that allowed delay duration will not be changed in later browser versions. Since implementations may differ between different browsers, avoid calling open asynchronously if possible.

<template>
  <!-- // Disable click and keydown behavior -->
  <wui-dropzone no-click no-keyboard>
    <template #info={ open }">
      <p class="text-center">Drag 'n' drop some files here ...</p>
      <wui-button @click="open">Open File Dialog</wui-button>
    </template>
  </wui-dropzone>
</template>

<!-- wui-dropzone-open-file-dialog-programmatically.vue -->

Upload Queue Manually

When a file is added to the drop zone, its status is set to queued (if files pass the internal validation check), meaning the file is now in the queue.

If you have the autoProcessQueue option set to true, the queue will be processed immediately after a file is dropped or an upload is finished by calling .processQueue() which checks how many files are currently being uploaded.

If you set autoProcessQueue to false then .processQueue() will never be called implicitly. This means that if you want to upload all the files currently in the queue, you have to invoke .processQueue() yourself.

<template>
  <wui-dropzone :auto-process-queue="false">
    <template #info="{ queuedFiles, processQueue }">
      <p class="text-center">Drag 'n' drop some files here ...</p>
      <wui-button v-if="queuedFiles.length" @click="processQueue"
        >Upload files</wui-button
      >
    </template>
  </wui-dropzone>
</template>

<!-- wui-dropzone-process-queue-manually.vue -->

Extending Dropzone

The component accepts a getFilesFromEvent prop that enhances the handling of dropped file system objects and allows more flexible use of them e.g. passing a function that accepts drop event of a folder and resolves it to an array of files adds plug-in functionality of folders drag-and-drop.

Though, note that the provided getFilesFromEvent fn must return a Promise with a list of File objects (or DataTransferItem of {kind: 'file'} when data cannot be accessed). Otherwise, the results will be discarded and none of the drag events callbacks will be invoked.

In case you need to extend the File with some additional properties, you should use Object.defineProperty() so that the result will still pass through our filter:

<template>
  <wui-dropzone :get-files-from-event="myCustomFileGetter" />
</template>

<script>
  export default {
    methods: {
      myCustomFileGetter(event) {
        const files = [];
        const fileList = event.dataTransfer
          ? event.dataTransfer.files
          : event.target.files;

        for (var i = 0; i < fileList.length; i++) {
          const file = fileList.item(i);

          Object.defineProperty(file, "myProp", {
            value: true,
          });

          files.push(file);
        }

        return files;
      },
    },
  };
</script>

<!-- wui-dropzone-get-files-from-event.vue -->

Custom Layouts

There are scoped slots for almost each part of the drop zone to render custom content.

default slot

The default scoped slot replaces the entire drop zone with custom content, but not the preview file list. Make sure you use the four getter functions from the slot scope for your drop zone root element (getRootProps(), getRootListeners()) and for the input form element (getInputProps(), getInputListeners()) to provide the drop zone functionality.

<template>
  <wui-dropzone>
    <template
      #default="{
        getRootProps,
        getRootListeners,
        getInputProps,
        getInputListeners,
        open,
      }"
    >
      <div
        v-bind="getRootProps({ class: 'my-dropzone-root' })"
        v-on="getRootListeners()"
      >
        <input v-bind="getInputProps()" v-on="getInputListeners()" />
        <p class="text-center">Drag 'n' drop some files here ...</p>
        <p class="text-center">or</p>
        <wui-button @click="open">Select files</wui-button>
      </div>
    </template>
  </wui-dropzone>
</template>

<!-- wui-dropzone-default-scoped-slot.vue -->

label slot

The label scoped slot replaces almost all of the drop zone with custom content, except for the drop zone root element and its functionality (mostly drag 'n' drop) and the preview file list, which remain. Since it also replaces the file element like the default slot, you have to create this element yourself and use the two getter functions (getInputProps() and getInputListeners()).

<template>
  <wui-dropzone>
    <template
      #label="{
        getInputProps,
        getInputListeners,
        open,
      }"
    >
      <label :id="dz-label" for="file-input" class="my-dropzone-label">
        <input
          v-bind="getInputProps({ id: 'file-input' })"
          v-on="getInputListeners()"
        />
        <p class="text-center">Drag 'n' drop some files here ...</p>
        <p class="text-center">or</p>
        <wui-button @click="open">Select files</wui-button>
      </label>
    </template>
  </wui-dropzone>
</template>

<!-- wui-dropzone-label-scoped-slot.vue -->

image slot

The image scoped slot replaces the drop zone wescale image with custom content.

busy slot

The busy scoped slot replaces the drop zone's default busy state with your own custom content, e. g. a custom spinner. The busy scoped slot is only rendered if disablePreviews is true and multiple is false and a file is uploading.

<template>
  <wui-dropzone>
    <template
      #busy="{
        file
        fileSize,
        uploadedFileSize,
        cancelUpload,
      }"
    >
      <div class="w-full">
        <span>{ file.file.name } </span>
        <div
          class="display--flex align-items-center justify-content-between"
          :style="compact && { order: 6 }"
        >
          <p class="m-0">
            <span class="text-muted">
              <span
                >{ uploadedFileSize.value } { uploadedFileSize.unit } / </span
              >{ fileSize.value } { fileSize.unit }</span
            >
          </p>
          <wui-button
            outline
            variant="link"
            class="wui-color--default"
            :title="t('dropzone.button.cancelUpload')"
            @click.stop="cancelUpload"
            ><wui-fa-icon icon="xmark"
          /></wui-button>
        </div>
        <wui-progress
          :value="file.upload.progress"
          class="flex-fill"
          height="2px"
        />
      </div>
    </template>
  </wui-dropzone>
</template>

<!-- wui-dropzone-busy-scoped-slot.vue -->

info-container slot

The info-container slot replaces the complete content on the right side of the drop zone, as the text and the "Select files" button.

info slot

The info slot replaces the content on the right side of the drop zone, except for the "Select files" button, which remains.

info-message slot

The info-message slot replaces only the first text (dropzone.message) on the right side of the drop zone.

info-message-allowed-extensions slot

The info-message-allowed-extensions slot replaces only the text for allowed file extensions (dropzone.messageAllowedExtensions) on the right side of the drop zone.

file-actions slot

Use the file-actions scoped slot to add one or more action icon buttons to every file preview.

<template>
  <wui-dropzone>
    <template #file-actions="{ id, status }">
      <wui-button
        v-if="status === 'success'"
        variant="link"
        title="Change visibility"
        @click="handleChangeVisibility(id)"
      >
        <wui-fa-icon
          :icon="getIsFileVisibileById(id) ? 'globe' : 'shield-halved'"
        />
      </wui-button>
    </template>
  </wui-dropzone>
</template>

<script>
  export default {
    data() {
      return {
        internalFileIds: [],
      };
    },
    methods: {
      getIsFileVisibileById(id) {
        return Boolean(this.internalFileIds.every((_id) => _id !== id));
      },
      deleteInternalFileStateById(id) {
        const index = this.internalFileIds.findIndex((_id) => _id === id);
        if (index > -1) this.internalFileIds.splice(index, 1);
      },
      handleChangeVisibility(id) {
        if (this.getIsFileVisibileById(id)) {
          this.internalFileIds.push(id);
          return;
        }
        this.deleteInternalFileStateById(id);
      },
    },
  };
</script>

<!-- wui-dropzone-file-actions-scoped-slot.vue -->

File list helper components

WuiVue provides additional helper child components for previewing files:

• wui-dropzone-file-list (alias wui-file-list)
• wui-dropzone-file-list-item (alias wui-file-list-item)

These components serve the purpose of displaying a custom preview of dropped or selected files elsewhere in your app.

file-list slot

With the file-list scoped slot you can render a custom preview of the files. Optionally, you can use the helper components mentioned above to create a consistent layout.

<template>
  <wui-dropzone>
    <template #file-list="{ files, remove, cancelUpload }">
      <p>Add some custom text or any other content here ...</p>

      <!-- You can use our helper components or your own layout -->
      <wui-dropzone-file-list v-if="files.length">
        <wui-dropzone-file-list-item
          v-for="file of files"
          :id="file.upload.uuid"
          :key="file.upload.uuid"
          :errors="file.errors"
          :file-name="file.file.name"
          :image-url="file.thumbnailDataURL"
          :bytes-sent="file.upload.bytesSent"
          :progress="file.upload.progress"
          :size="file.file.size"
          :status="file.status"
          tag="li"
          :type="file.file.type"
          :add-download-link
          @download="handleDownload"
          @remove="remove"
          @cancel-upload="cancelUpload"
        />
      </wui-dropzone-file-list>
    </template>
  </wui-dropzone>
</template>

<script>
  export default {
    methods: {
      // `id` is the unique file.upload.uuid
      handleDownload(id) {
        // do something
      },
    },
  };
</script>

<!-- wui-dropzone-file-list-scoped-slot.vue -->

Component reference

<wui-dropzone>

• <wui-dropzone> Properties
• <wui-dropzone> Slots
• <wui-dropzone> Events

Properties

Slots

Events

<wui-dropzone-file-list>

• <wui-dropzone-file-list> Component aliases
• <wui-dropzone-file-list> Properties
• <wui-dropzone-file-list> Slots

Component aliases

<wui-dropzone-file-list> can also be used via the following aliases:

• <wui-file-list>

Properties

Slots

<wui-dropzone-file-list-item>

• <wui-dropzone-file-list-item> Component aliases
• <wui-dropzone-file-list-item> Properties
• <wui-dropzone-file-list-item> Slots
• <wui-dropzone-file-list-item> Events

Component aliases

<wui-dropzone-file-list-item> can also be used via the following aliases:

• <wui-file-list-item>

Properties

Slots

Events

Importing individual components

You can import individual components into your project via the following named exports:

Example

import { WuiDropzone } from "@wui/wui-vue/lib";
Vue.component("wui-dropzone", WuiDropzone);

Importing as a Vue.js plugin

This plugin includes all of the above listed individual components. Plugins also include any component aliases.

Example

import { DropzonePlugin } from "@wui/wui-vue/lib";
Vue.use(DropzonePlugin);