Uppy core
Uppy can be an uploader and an interface with a lot of features. Features can be
added incrementally with plugins, but Uppy can be as bare bones as you want it
to be. So we build Uppy’s heart, @uppy/core
, as a standalone orchestrator. It
acts as a state manager, event emitter, and restrictions handler.
When should I use it?
@uppy/core
is the fundament of the Uppy ecosystem, the orchestrator for all
added plugins. No matter the uploading experience you’re looking for, it all
starts with installing this plugin.
You can use @uppy/core
and
build your own UI or go for the
Dashboard integration. For an uploading plugin, you can refer
to choosing the uploader you need.
If you want to see how it all comes together, checkout the examples.
Install
- NPM
- Yarn
- CDN
npm install @uppy/core
yarn add @uppy/core
The bundle consists of most Uppy plugins, so this method is not recommended for production, as your users will have to download all plugins when you are likely using only a few.
It can be useful to speed up your development environment, so don't hesitate to use it to get you started.
<!-- 1. Add CSS to `<head>` -->
<link href="https://releases.transloadit.com/uppy/v3.20.0/uppy.min.css" rel="stylesheet">
<!-- 2. Initialize -->
<div id="uppy"></div>
<script type="module">
import { Uppy } from "https://releases.transloadit.com/uppy/v3.20.0/uppy.min.mjs"
const uppy = new Uppy()
</script>
Use
@uppy/core
has four exports: Uppy
, UIPlugin
, BasePlugin
, and
debugLogger
. The default export is the Uppy
class.
Working with Uppy files
Uppy keeps files in state with the File
browser API, but it’s wrapped in
an Object
to be able to add more data to it, which we call an Uppy file. All
these properties can be useful for plugins and side-effects (such as
events).
Mutating these properties should be done through methods.
Uppy file properties
file.source
Name of the plugin that was responsible for adding this file. Typically a remote
provider plugin like 'GoogleDrive'
or a UI plugin like 'DragDrop'
.
file.id
Unique ID for the file.
file.name
The name of the file.
file.meta
Object containing file metadata. Any file metadata should be JSON-serializable.
file.type
MIME type of the file. This may actually be guessed if a file type was not provided by the user’s browser, so this is a best-effort value and not guaranteed to be correct.
file.data
For local files, this is the actual File
or Blob
object representing
the file contents.
For files that are imported from remote providers, the file data is not available in the browser.
file.progress
An object with upload progress data.
Properties
bytesUploaded
- Number of bytes uploaded so far.bytesTotal
- Number of bytes that must be uploaded in total.uploadStarted
- Null if the upload has not started yet. Once started, this property stores a UNIX timestamp. Note that this is only set after preprocessing.uploadComplete
- Boolean indicating if the upload has completed. Note this does not mean that postprocessing has completed, too.percentage
- Integer percentage between 0 and 100.
file.size
Size in bytes of the file.
file.isRemote
Boolean: is this file imported from a remote provider?
file.remote
Grab bag of data for remote providers. Generally not interesting for end users.
file.preview
An optional URL to a visual thumbnail for the file.
file.uploadURL
When an upload is completed, this may contain a URL to the uploaded file. Depending on server configuration it may not be accessible or correct.
new Uppy(options?)
import Uppy from '@uppy/core';
const uppy = new Uppy();
Options
id
A site-wide unique ID for the instance (string
, default: uppy
).
If several Uppy instances are being used, for instance, on two different pages,
an id
should be specified. This allows Uppy to store information in
localStorage
without colliding with other Uppy instances.
This ID should be persistent across page reloads and navigation—it shouldn’t be a random number that is different every time Uppy is loaded.
autoProceed
Upload as soon as files are added (boolean
, default: false
).
By default Uppy will wait for an upload button to be pressed in the UI, or the
.upload()
method to be called before starting an upload. Setting this to
true
will start uploading automatically after the first file is selected
allowMultipleUploadBatches
Whether to allow several upload batches (boolean
, default: true
).
This means several calls to .upload()
, or a user adding more files after
already uploading some. An upload batch is made up of the files that were added
since the earlier .upload()
call.
With this option set to true
, users can upload some files, and then add more
files and upload those as well. A model use case for this is uploading images to
a gallery or adding attachments to an email.
With this option set to false
, users can upload some files, and you can listen
for the 'complete'
event to continue to the next step in your
app’s upload flow. A typical use case for this is uploading a new profile
picture. If you are integrating with an existing HTML form, this option gives
the closest behaviour to a bare <input type="file">
.
debug
Whether to send debugging and warning logs (boolean
, default: false
).
Setting this to true
sets the logger
to
debugLogger
.
logger
Logger used for uppy.log
(Object
, default:
justErrorsLogger
).
By providing your own logger
, you can send the debug information to a server,
choose to log errors only, etc.
Set logger
to debugLogger
to get debug info output to the
browser console:
You can also provide your own logger object: it should expose debug
, warn
and error
methods, as shown in the examples below.
Here’s an example of a logger
that does nothing:
const nullLogger = {
debug: (...args) => {},
warn: (...args) => {},
error: (...args) => {},
};
restrictions
Conditions for restricting an upload (Object
, default: {}
).
Property | Value | Description |
---|---|---|
maxFileSize | number | maximum file size in bytes for each individual file |
minFileSize | number | minimum file size in bytes for each individual file |
maxTotalFileSize | number | maximum file size in bytes for all the files that can be selected for upload |
maxNumberOfFiles | number | total number of files that can be selected |
minNumberOfFiles | number | minimum number of files that must be selected before the upload |
allowedFileTypes | Array | wildcards image/* , or exact mime types image/jpeg , or file extensions .jpg : ['image/*', '.jpg', '.jpeg', '.png', '.gif'] |
requiredMetaFields | Array<string> | make keys from the meta object in every file required before uploading |
maxNumberOfFiles
also affects the number of files a user is able to select via
the system file dialog in UI plugins like DragDrop
, FileInput
and
Dashboard
. When set to 1
, they will only be able to select a single file.
When null
or another number is provided, they will be able to select several
files.
allowedFileTypes
gets passed to the file system dialog via the
<input>
accept attribute, so only types supported by the browser will work.
If you’d like to force a certain meta field data to be entered before the
upload, you can
do so using onBeforeUpload
.
If you need to restrict allowedFileTypes
to a file extension with double dots,
like .nii.gz
, you can do so by
setting allowedFileTypes
to the last part of the extension, allowedFileTypes: ['.gz']
, and then using onBeforeFileAdded
to filter for .nii.gz
.
meta
Key/value pairs to add to each file’s metadata
(Object
, default: {}
).
Two methods also exist for updating metadata
: setMeta
and
setFileMeta
.
Metadata can also be added from a <form>
element on your page, through the
Form plugin or through the UI if you are using Dashboard with the
metaFields
option.
onBeforeFileAdded(file, files)
A function called before a file is added to Uppy (Function
, default:
(files, file) => !Object.hasOwn(files, file.id)
).
Use this function to run any number of custom checks on the selected file, or manipulate it, for instance, by optimizing a file name. You can also allow duplicate files with this.
You can return true
to keep the file as is, false
to remove the file, or
return a modified file.
This method is intended for quick synchronous checks and modifications only. If you need to do an async API call, or heavy work on a file (like compression or encryption), you should use a custom plugin instead.
No notification will be shown to the user about a file not passing validation by
default. We recommend showing a message using
uppy.info()
and logging to console for debugging
purposes via uppy.log()
.
Filter, change, and abort example
Allow all files, also duplicate files. This will replace the file if it has not been uploaded. If you upload a duplicate file again it depends on your upload plugin and backend how it is handled.
const uppy = new Uppy({
// ...
onBeforeFileAdded: () => true,
Keep only files under a condition:
const uppy = new Uppy({
// ...
onBeforeFileAdded: (currentFile, files) => {
if (currentFile.name === 'forest-IMG_0616.jpg') {
return true
}
return false
},
Change all file names:
const uppy = new Uppy({
// ...
onBeforeFileAdded: (currentFile, files) => {
const modifiedFile = {
...currentFile,
name: `${currentFile.name}__${Date.now()}`,
}
return modifiedFile
},
Abort a file:
const uppy = new Uppy({
// ...
onBeforeFileAdded: (currentFile, files) => {
if (!currentFile.type) {
// log to console
uppy.log(`Skipping file because it has no type`);
// show error message to the user
uppy.info(`Skipping file because it has no type`, 'error', 500);
return false;
}
},
});
onBeforeUpload(files)
A function called before when upload is initiated (Function
, default:
(files) => files
).
Use this to check if all files or their total number match your requirements, or manipulate all the files at once before upload.
You can return true
to continue the upload, false
to cancel it, or return
modified files.
This method is intended for quick synchronous checks and modifications only. If you need to do an async API call, or heavy work on a file (like compression or encryption), you should use a custom plugin instead.
No notification will be shown to the user about a file not passing validation by
default. We recommend showing a message using
uppy.info()
and logging to console for debugging
purposes via uppy.log()
.
Change and abort example
Change all file names:
const uppy = new Uppy({
// ...
onBeforeUpload: (files) => {
// We’ll be careful to return a new object, not mutating the original `files`
const updatedFiles = {};
Object.keys(files).forEach((fileID) => {
updatedFiles[fileID] = {
...files[fileID],
name: `${myCustomPrefix}__${files[fileID].name}`,
};
});
return updatedFiles;
},
});
Abort an upload:
const uppy = new Uppy({
// ...
onBeforeUpload: (files) => {
if (Object.keys(files).length < 2) {
// log to console
uppy.log(
`Aborting upload because only ${
Object.keys(files).length
} files were selected`,
);
// show error message to the user
uppy.info(`You have to select at least 2 files`, 'error', 500);
return false;
}
return true;
},
});
locale
You can override locale strings by passing the strings
object with the keys
you want to override.
Array indexed objects are used for pluralisation.
If you want a different language it’s better to use locales.
module.exports = {
strings: {
addBulkFilesFailed: {
0: 'Failed to add %{smart_count} file due to an internal error',
1: 'Failed to add %{smart_count} files due to internal errors',
},
youCanOnlyUploadX: {
0: 'You can only upload %{smart_count} file',
1: 'You can only upload %{smart_count} files',
},
youHaveToAtLeastSelectX: {
0: 'You have to select at least %{smart_count} file',
1: 'You have to select at least %{smart_count} files',
},
exceedsSize: '%{file} exceeds maximum allowed size of %{size}',
missingRequiredMetaField: 'Missing required meta fields',
missingRequiredMetaFieldOnFile:
'Missing required meta fields in %{fileName}',
inferiorSize: 'This file is smaller than the allowed size of %{size}',
youCanOnlyUploadFileTypes: 'You can only upload: %{types}',
noMoreFilesAllowed: 'Cannot add more files',
noDuplicates:
"Cannot add the duplicate file '%{fileName}', it already exists",
companionError: 'Connection with Companion failed',
authAborted: 'Authentication aborted',
companionUnauthorizeHint:
'To unauthorize to your %{provider} account, please go to %{url}',
failedToUpload: 'Failed to upload %{file}',
noInternetConnection: 'No Internet connection',
connectedToInternet: 'Connected to the Internet',
// Strings for remote providers
noFilesFound: 'You have no files or folders here',
selectX: {
0: 'Select %{smart_count}',
1: 'Select %{smart_count}',
},
allFilesFromFolderNamed: 'All files from folder %{name}',
openFolderNamed: 'Open folder %{name}',
cancel: 'Cancel',
logOut: 'Log out',
filter: 'Filter',
resetFilter: 'Reset filter',
loading: 'Loading...',
authenticateWithTitle:
'Please authenticate with %{pluginName} to select files',
authenticateWith: 'Connect to %{pluginName}',
signInWithGoogle: 'Sign in with Google',
searchImages: 'Search for images',
enterTextToSearch: 'Enter text to search for images',
search: 'Search',
emptyFolderAdded: 'No files were added from empty folder',
folderAlreadyAdded: 'The folder "%{folder}" was already added',
folderAdded: {
0: 'Added %{smart_count} file from %{folder}',
1: 'Added %{smart_count} files from %{folder}',
},
},
};
store
The store that is used to keep track of internal state (Object
, default:
DefaultStore
).
This option can be used to plug Uppy state into an external state management library, such as Redux.
infoTimeout
How long an Informer notification will be visible (number
,
default: 5000
).
Methods
use(plugin, opts)
Add a plugin to Uppy, with an optional plugin options object.
import Uppy from '@uppy/core';
import DragDrop from '@uppy/drag-drop';
const uppy = new Uppy();
uppy.use(DragDrop, { target: 'body' });
removePlugin(instance)
Uninstall and remove a plugin.
getPlugin(id)
Get a plugin by its id
to access its methods.
getID()
Get the Uppy instance ID, see the id
option.
addFile(file)
Add a new file to Uppy’s internal state. addFile
will return the generated id
for the file that was added.
addFile
gives an error if the file cannot be added, either because
onBeforeFileAdded(file)
gave an error, or because uppy.opts.restrictions
checks failed.
uppy.addFile({
name: 'my-file.jpg', // file name
type: 'image/jpeg', // file type
data: blob, // file blob
meta: {
// optional, store the directory path of a file so Uppy can tell identical files in different directories apart.
relativePath: webkitFileSystemEntry.relativePath,
},
source: 'Local', // optional, determines the source of the file, for example, Instagram.
isRemote: false, // optional, set to true if actual file is not in the browser, but on some remote server, for example,
// when using companion in combination with Instagram.
});
If you try to add a file that already exists, addFile
will throw an error.
Unless that duplicate file was dropped with a folder — duplicate files from
different folders are allowed, when selected with that folder. This is because
we add file.meta.relativePath
to the file.id
.
Checkout working with Uppy files.
If uppy.opts.autoProceed === true
, Uppy will begin uploading automatically
when files are added.
Sometimes you might need to add a remote file to Uppy. This can be achieved by fetching the file, then creating a Blob object, or using the Url plugin with Companion.
Sometimes you might need to mark some files as “already uploaded”, so that the
user sees them, but they won’t actually be uploaded by Uppy. This can be
achieved by
looping through files and setting uploadComplete: true, uploadStarted: true
on them
removeFile(fileID)
Remove a file from Uppy. Removing a file that is already being uploaded cancels that upload.
uppy.removeFile('uppyteamkongjpg1501851828779');
getFile(fileID)
Get a specific Uppy file by its ID.
const file = uppy.getFile('uppyteamkongjpg1501851828779');
getFiles()
Get an array of all added Uppy files.
const files = uppy.getFiles();
upload()
Start uploading added files.
Returns a Promise result
that resolves with an object containing two arrays of
uploaded files:
result.successful
- Files that were uploaded successfully.result.failed
- Files that did not upload successfully. These files will have a.error
property describing what went wrong.
uppy.upload().then((result) => {
console.info('Successful uploads:', result.successful);
if (result.failed.length > 0) {
console.error('Errors:');
result.failed.forEach((file) => {
console.error(file.error);
});
}
});
pauseResume(fileID)
Toggle pause/resume on an upload. Will only work if resumable upload plugin, such as Tus, is used.
pauseAll()
Pause all uploads. Will only work if a resumable upload plugin, such as Tus, is used.
resumeAll()
Resume all uploads. Will only work if resumable upload plugin, such as Tus, is used.
retryUpload(fileID)
Retry an upload (after an error, for example).
retryAll()
Retry all uploads (after an error, for example).
cancelAll({ reason: 'user' })
Argument | Type | Description |
---|---|---|
reason | string | The reason for canceling. Plugins can use this to provide different cleanup behavior (Transloadit plugin cancels an Assembly if user clicked on the “cancel” button). Possible values are: user (default) - The user has pressed “cancel”; unmount - The Uppy instance has been closed programmatically |
Cancel all uploads, reset progress and remove all files.
setState(patch)
Update Uppy’s internal state. Usually, this method is called internally, but in some cases it might be useful to alter something directly, especially when implementing your own plugins.
Uppy’s default state on initialization:
const state = {
plugins: {},
files: {},
currentUploads: {},
capabilities: {
resumableUploads: false,
},
totalProgress: 0,
meta: { ...this.opts.meta },
info: {
isHidden: true,
type: 'info',
message: '',
},
};
Updating state:
uppy.setState({ smth: true });
State in Uppy is considered to be immutable. When updating values, make sure not mutate them, but instead create copies. See Redux docs for more info on this.
getState()
Returns the current state from the Store.
setFileState(fileID, state)
Update the state for a single file. This is mostly useful for plugins that may want to store data on Uppy files, or need to pass file-specific configurations to other plugins that support it.
fileID
is the string file ID. state
is an object that will be merged into
the file’s state object.
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. Calling setMeta
will also merge
newly added meta data with files that had been selected before.
uppy.setMeta({ resize: 1500, token: 'ab5kjfg' });
setFileMeta(fileID, data)
Update metadata for a specific file.
uppy.setFileMeta('myfileID', { resize: 1500 });
setOptions(opts)
Change the options Uppy initialized with.
const uppy = new Uppy();
uppy.setOptions({
restrictions: { maxNumberOfFiles: 3 },
autoProceed: true,
});
uppy.setOptions({
locale: {
strings: {
cancel: 'Отмена',
},
},
});
You can also change options for plugin:
// Change width of the Dashboard drag-and-drop aread on the fly
uppy.getPlugin('Dashboard').setOptions({
width: 300,
});
close({ reason: 'user' })
Argument | Type | Description |
---|---|---|
reason | string | The reason for canceling. Plugins can use this to provide different cleanup behavior (Transloadit plugin cancels an Assembly if user clicked on the “cancel” button). Possible values are: user (default) - The user has pressed “cancel”; unmount - The Uppy instance has been closed programmatically |
Uninstall all plugins and close down this Uppy instance. Also runs
uppy.cancelAll()
before uninstalling.