@yst/vue-file-uploader

Vue File Uploader

A template-like wrapper component that adds file-upload functionalities to your components.

Being "renderless", it doesn't insert (neither wrap your components around with) any additional element, except for the required input one which is hidden from the view anyway.

Installation

NPM

$ npm install --save @yst/vue-file-uploader

Yarn

$ yarn add @yst/vue-file-uploader

Component Registration

As plugin (globally accessible)

Recommended for custom configurations.

import Vue from 'vue';
import VueFileUploader from '@yst/vue-file-uploader';

const opts = {
  // See: "Plugin Options" below
};

Vue.use(VueFileUploader, opts);

As local component

import Vue from 'vue';
import { VueFileUploader } from '@yst/vue-file-uploader';

export default {
  components: {
    VueFileUploader
  }
}

Examples

Default Event Handler

<template>
  <vue-file-uploader v-slot="{ select }" @selected="onFileSelected">
    <button @click="select">Select a file</button>
  </vue-file-uploader>
</template>

<script>
  export default {
    methods: {
      onFileSelected(files, el) {
        // Do something with the selected files here
      }
    }
  }
</script>

Asynchronous

<template>
  <vue-file-uploader v-slot="{ select }">
    <button @click="openFileDialog(select)">Select a file</button>
  </vue-file-uploader>
</template>

<script>
  export default {
    methods: {
      async openFileDialog(select) {
        const { files, el } = await select();
        
        // Do something with the selected files here
      }
    }
  }
</script>

File-size Policy/Rules Validations

<template>
  <vue-file-uploader 
    v-slot="{ select, tooLarge }" 
    :max-file-size="(1024 * 1024)"
    :accept="['image/*', '.pdf']">

    <!-- Using custom button component -->
    <my-button 
      @click="openFileDialog(select)"
      :style="{ borderColor: tooLarge ? 'red' : 'inherit' }"
      label="Select a file">
    </my-button>

  </vue-file-uploader>
</template>

<template>
  <vue-file-uploader 
    v-slot="{ select, tooMany, totallyTooLarge }" 
    :max-file-count="maxFileCount"
    :max-total-size="maxTotalSize"
    multiple>

    <!-- Just like the regular <template>, you need exactly one root element -->
    <div class="uploader-container">
      <input @click="select" type="button" value="Select a file" />
      
      <ul class="uploader-error-bag">
        <li v-if="tooMany">Please select no more than {{maxFileCount}} files.</li>
        <li v-if="totallyTooLarge">The total size is too large.</li>
      </ul>
    </div>

  </vue-file-uploader>
</template>

<script>
  export default {
    data: () => ({
      maxFileCount: 2,
      maxTotalSize: (1024 * 1024) * 2 // 2mb
    })
  }
</script>

---

The first two examples above (when rendered) will result in...

<button>Select a file</button>

<input type="file" id="some-unique-id" style="display: none" aria-hidden="true" />

...leaving your component clean and uncluttered.

To make it even "cleaner", consider specifying an uploaderContainerId for these hidden input elements to nest under its element as a container.

Demo

via CodeSandbox

Plugin Options

uploaderContainerId

• type: string
• default: undefined

Any valid HTML id selector.

By default, each (hidden) input[type="file"] will be positioned afterend of the target element/component itself — by specifying a container id, you could mount them somewhere else. Please make sure that the container exists in the DOM tree to mount to.

componentName

• type: string
• default: 'VueFileUploader'

The component name to use on the <template> when registered globally.

Props

accept

• type: string | Array<string>
• default: '' (any type of file)

A string (or an array of strings) that defines the file types the file input should accept.

multiple

• type: boolean
• default: false

Allows users to select one or more files. See multiple.

capture

• type: string
• default: undefined

Specifies which camera to use for capturing image or video data. Accepted values are user and environment. Read more.

maxFileSize

• type: number | string
• default: 0

Maximum size of individual files in bytes.

maxTotalSize

• type: number | string
• default: 0

Maximum size of all files combined in bytes.

maxFileCount

• type: number | string
• default: 0

Maximum number of files to contain.

errorIfInvalid

• type: boolean
• default: false

Throws an error if any validation rule is violated.

reactive

• type: boolean
• default: false

Enables reactivity for the core attributes, with slight performance penalties.

Scoped Slots

default(props: object)

Mimicking the v-slot built-in directive, this renderless component simply provides yours with the underlying file-upload functionalities, and whatnots.

It's worth nothing (again) that as a wrapping, template-like component, it is essentially non-existent — meaning, your target components themselves would be the real focus here. Go to examples.

props.select

• type: Function
• arguments: files, element
• returns: Promise<{ files: Array<File>, el: HTMLInputElement }>

props.files

• type: Array<File>

The selected files. See: Instance properties.

props.tooLarge

• type: boolean

Determines if the individual files exceed the maxFileSize (in bytes).

props.totallyTooLarge

• type: boolean

Determines if all files combined exceed the maxTotalSize (in bytes).

props.tooMany

• type: boolean

Determines if the total number of files exceeds the maxFileCount.

Events

selected(...args)

• args.files: Array<File>
• args.el: HTMLInputElement

Emitted when a file has been selected.

invalid(violationTypes)

• violationTypes: Object<string, boolean>

Emitted if any validation rule is violated, while passing the rules map that triggers the event.

Example with destructured values:

<vue-file-uploader @invalid="onInvalid">
...

onInvalid({ tooLarge, tooMany }) {
  if (tooMany) {
    // Do something
  }
}

error(ex)

• ex: Error

Emitted if any exception occurs during the whole process, including rules violations or invalid files (needs errorIfInvalid prop enabled) and other generic exceptions.

License

MIT