Uppy-Vuex [alpha]

A lightweight Vuex wrapper around the Uppy file upload library.

Installation

npm install uppy-vuex

Import & Initialization

import Vuex from 'vuex';
import UppyVuex from "uppy-vuex";


// Add UppyVuex as a Vuex module
// (for hot installation with code-splitting, see Appendix)
const store = new Vuex.Store({
    modules: {
        uppy: UppyVuex
    }
})

// Initialize Uppy
store.dispatch("uppy/init");

// You can now use uppy from anywhere in your app!

You'll need to install one of Uppy's uploader plugins before Uppy can do any useful uploading. See their excellent getting started docs.

Usage

Uppy-Vuex exposes the complete Uppy Core API. All methods are available by dispatching uppy/<uppy method>, or by calling the uppy/<getter> getters.

Caution: Some method signatures are slightly different, so read carefully! (The changed methods are marked with ❗️)

Note: Uppy-Vuex is a namespaced module. This means that all getters and actions must be prefaced with uppy/

Getters

|Usage|Effect|Doc link| |---|---|---|---| |getters["uppy/isReady"]| Has the underlying Uppy instance been initialized yet? (If false, dispatch uppy/init)| None (Uppy-Vuex only)| |getters["uppy/getUppyInstance"] | Access the underlying Uppy instance | None (Uppy-Vuex only)| |getters["uppy/getFile"](fileID)| Get a specific file object by its ID. | 🔗 Docs| |getters["uppy/getFiles"]| Get an array of all file objects in Uppy.. | 🔗 Docs| |getters["uppy/getID"]|Get the Uppy instance ID|🔗 Docs| |getters["uppy/getPlugin"](pluginID)|Get a plugin by its id to access its methods.|🔗 Docs| |getters["uppy/getState"]|Returns the current state from the Store.|🔗 Docs|

Actions

All Uppy active methods are actions, and not mutations for the sake of simplicity. Uppy-Vuex does not define any mutations. All actions return the result of the underlying Uppy method.

Basic

|Usage|Effect|Notes|Doc link| |---|---|---|---| |dispatch("uppy/init", uppyOptions)| Initialize the underlying Uppy instance | uppyOptions is what would be passed to the Uppy() constructor. |🔗 Docs| |dispatch("uppy/addFile", fileObject)| Add a new file to Uppy’s internal state. | |🔗 Docs| |dispatch("uppy/removeFile", fileID)| Remove a file from Uppy. | |🔗 Docs| |dispatch("uppy/upload")| Start uploading selected files. | Return a Promise that yields a results object {successful: [], failed: []}|🔗 Docs|

Pause / Resume

These will only work if the upload plugin supports resumable uploads, such as Tus.

|Usage|Effect| Doc link| |---|---|---| |dispatch("uppy/pauseResume", fileID)| Toggle pause/resume on an upload. |🔗 Docs| |dispatch("uppy/pauseAll")| Pause all uploads. |🔗 Docs| |dispatch("uppy/resumeAll")| Resumes all uploads. |🔗 Docs|

Retry

|Usage|Effect|Notes|Doc link| |---|---|---|---| |dispatch("uppy/retryUpload", fileID)| Retry an upload (after an error, for example). | |🔗 Docs| |dispatch("uppy/retryAll")| Retry all uploads (after an error, for example). | |🔗 Docs|

Cancellation and Teardown

|Usage|Effect|Notes|Doc link| |---|---|---|---| |dispatch("uppy/cancelAll")| Cancel all uploads, reset progress and remove all files. | |🔗 Docs| |dispatch("uppy/reset")| Stop all uploads in progress and clear file selection, set progress to 0.| Restores Uppy to pristine pre-interaction state.|🔗 Docs| |dispatch("uppy/close")| Uninstall all plugins and close down this Uppy instance. Also runs uppy/reset before uninstalling.| All subsequent actions will fail unless uppy/init is dispatched again|🔗 Docs|

Advanced

❗️Some of these actions have modified method signatures. |Usage|Effect|Notes|Doc link| |---|---|---|---| |dispatch("uppy/setFileMeta", {fileID, data})| Update metadata for a specific file. | |🔗 Docs| |dispatch("uppy/setMeta", data)| Alters global meta object in state, the one that can be set in Uppy options and gets merged with all newly added files.. | |🔗 Docs| |dispatch("uppy/ setFileState", {fileID, fileState})| Update the state for a single file. | |🔗 Docs| |dispatch("uppy/ setState", patch)| Update Uppy’s internal state (See docs). | See also: the getState getter |🔗 Docs|

Plugins

❗️These actions have modified method signatures.

|Usage|Effect|Notes|Doc link| |---|---|---|---| |dispatch("uppy/use", {plugin, options})| Add a plugin to Uppy, with an optional plugin options object. | |🔗 Docs| |dispatch("uppy/removePlugin", instance)| Uninstall and remove a plugin. | See also: the getPlugin getter|🔗 Docs|

Registering for Events

❗️These actions have modified method signatures.

|Usage|Effect|Notes|Doc link| |---|---|---|---| |dispatch("uppy/on", {event, callback})| Subscribe to an uppy-event. | See the full list of events |🔗 Docs| |dispatch("uppy/off", {event, callback})| Unsubscribe to an uppy-event. | See the full list of events |🔗 Docs|

Uppy Logging

❗️These actions have modified method signatures.

|Usage|Effect|Notes|Doc link| |---|---|---|---| |dispatch("uppy/log", {message, type})| Logs to the console, only if uppy.opts.debug is set to true. | ❗️Silent in production|🔗 Docs| |dispatch("uppy/info", {message, type, duration})|Sets a message in state, with optional details, that can be shown by notification UI plugins. | |🔗 Docs|

Limitations

• UppyVuex can only contain a single Uppy instance at a time. If you need to have multiple seperate uploaders on a page, the UppyVuex will not meet your needs.

Bugs

UppyVuex contains practically no logic, so you're probably best off trying to repro your issues on Uppy itself. Issues can be filed against this repo.

Contributing

The current maintainer is AnalyzePlatypus.