Vaadin WC API reference

Description

<vaadin-upload> is a Web Component for uploading multiple files with drag and drop support.

Example:

<vaadin-upload></vaadin-upload>

Styling

The following shadow DOM parts are available for styling:

Part name Description
primary-buttons Upload container
drop-label Element wrapping drop label and icon

The following state attributes are available for styling:

Attribute Description Part name
disabled Set when the element is disabled :host
nodrop Set when drag and drop is disabled (e. g., on touch devices) :host
dragover A file is being dragged over the element :host
dragover-valid A dragged file is valid with maxFiles and accept criteria :host
max-files-reached The maximum number of files that the user is allowed to add to the upload has been reached :host

See Styling Components documentation.

Properties

accept

Type: string

Specifies the types of files that the server accepts. Syntax: a comma-separated list of MIME type patterns (wildcards are allowed) or file extensions. Notice that MIME types are widely supported, while file extensions are only implemented in certain browsers, so avoid using it. Example: accept="video/*,image/tiff" or accept=".pdf,audio/mp3"

capture

Type: string | null | undefined

Pass-through to input's capture attribute. Allows user to trigger device inputs such as camera or microphone immediately.

disabled

Type: boolean

If true, the user cannot interact with this element.

files

Type: UploadFile[]

The array of files being processed, or already uploaded.

Each element is a File object with a number of extra properties to track the upload process:

  • uploadTarget: The target URL used to upload this file.
  • elapsed: Elapsed time since the upload started.
  • elapsedStr: Human-readable elapsed time.
  • remaining: Number of seconds remaining for the upload to finish.
  • remainingStr: Human-readable remaining time for the upload to finish.
  • progress: Percentage of the file already uploaded.
  • speed: Upload speed in kB/s.
  • size: File size in bytes.
  • totalStr: Human-readable total size of the file.
  • loaded: Bytes transferred so far.
  • loadedStr: Human-readable uploaded size at the moment.
  • status: Status of the upload process.
  • error: Error message in case the upload failed.
  • abort: True if the file was canceled by the user.
  • complete: True when the file was transferred to the server.
  • uploading: True while transferring data to the server.

See also: UploadFile

formDataName

Type: string

Specifies the 'name' property at Content-Disposition

headers

Type: string | object | null

Key-Value map to send to the server. If you set this property as an attribute, use a valid JSON string, for example:

<vaadin-upload headers='{"X-Foo": "Bar"}'></vaadin-upload>

i18n

Type: UploadI18n

The object used to localize this component. To change the default localization, replace this with an object that provides all properties, or just the individual properties you want to change.

The object has the following JSON structure and default values:

{
  dropFiles: {
    one: 'Drop file here',
    many: 'Drop files here'
  },
  addFiles: {
    one: 'Upload File...',
    many: 'Upload Files...'
  },
  error: {
    tooManyFiles: 'Too Many Files.',
    fileIsTooBig: 'File is Too Big.',
    incorrectFileType: 'Incorrect File Type.'
  },
  uploading: {
    status: {
      connecting: 'Connecting...',
      stalled: 'Stalled',
      processing: 'Processing File...',
      held: 'Queued'
    },
    remainingTime: {
      prefix: 'remaining time: ',
      unknown: 'unknown remaining time'
    },
    error: {
      serverUnavailable: 'Upload failed, please try again later',
      unexpectedServerError: 'Upload failed due to server error',
      forbidden: 'Upload forbidden'
    }
  },
  file: {
    retry: 'Retry',
    start: 'Start',
    remove: 'Remove'
  },
  units: {
    size: ['B', 'kB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'],
    sizeBase: 1000
  },
  formatSize: function(bytes) {
    // returns the size followed by the best suitable unit
  },
  formatTime: function(seconds, [secs, mins, hours]) {
    // returns a 'HH:MM:SS' string
  }
}

See also: UploadI18n

maxFiles

Type: number

Limit of files to upload, by default it is unlimited. If the value is set to one, native file browser will prevent selecting multiple files.

maxFileSize

Type: number

Specifies the maximum file size in bytes allowed to upload. Notice that it is a client-side constraint, which will be checked before sending the request. Obviously you need to do the same validation in the server-side and be sure that they are aligned.

maxFilesReached

Type: boolean

Specifies if the maximum number of files have been uploaded

method

Type: UploadMethod

HTTP Method used to send the files. Only POST and PUT are allowed.

See also: UploadMethod

noAuto

Type: boolean

Prevents upload(s) from immediately uploading upon adding file(s). When set, you must manually trigger uploads using the uploadFiles method

nodrop

Type: boolean

Define whether the element supports dropping files on it for uploading. By default it's enabled in desktop and disabled in touch devices because mobile devices do not support drag events in general. Setting it false means that drop is enabled even in touch-devices, and true disables drop in all devices.

target

Type: string

The server URL. The default value is an empty string, which means that window.location will be used.

timeout

Type: number

Max time in milliseconds for the entire upload process, if exceeded the request will be aborted. Zero means that there is no timeout.

withCredentials

Type: boolean

Set the withCredentials flag on the request.

Methods

uploadFiles

Type: (files?: UploadFile | UploadFile[] | undefined) => void

Triggers the upload of any files that are not completed

Events

file-reject

Type: UploadFileRejectEvent

Fired when a file cannot be added to the queue due to a constrain: file-size, file-type or maxFiles

files-changed

Type: UploadFilesChangedEvent

Fired when the files property changes.

max-files-reached-changed

Type: UploadMaxFilesReachedChangedEvent

Fired when the maxFilesReached property changes.

upload-abort

Type: CustomEvent

Fired when retry abort is requested. If the default is prevented, then the file upload would not be aborted.

upload-before

Type: CustomEvent

Fired before the XHR is opened. Could be used for changing the request URL. If the default is prevented, then XHR would not be opened.

upload-error

Type: CustomEvent

Fired in case the upload process failed.

upload-progress

Type: CustomEvent

Fired as many times as the progress is updated.

upload-request

Type: CustomEvent

Fired when the XHR has been opened but not sent yet. Useful for appending data keys to the FormData object, for changing some parameters like headers, etc. If the event is defaultPrevented, vaadin-upload will not send the request allowing the user to do something on his own.

upload-response

Type: CustomEvent

Fired when we have the actual server response, and before the component analyses it. It's useful for developers to make the upload fail depending on the server response. If the event is defaultPrevented the vaadin-upload will return allowing the user to do something on his own like retry the upload, etc. since he has full access to the xhr and file objects. Otherwise, if the event is not prevented default vaadin-upload continues with the normal workflow checking the xhr.status and file.error which also might be modified by the user to force a customized response.

upload-retry

Type: CustomEvent

Fired when retry upload is requested. If the default is prevented, then retry would not be performed.

upload-start

Type: CustomEvent

Fired when the XHR is sent.

upload-success

Type: CustomEvent

Fired in case the upload process succeed.

Types

UploadFile

export interface UploadFile extends File {
  uploadTarget: string;
  elapsed: number;
  elapsedStr: string;
  remaining: number;
  remainingStr: string;
  progress: number;
  speed: number;
  totalStr: string;
  loaded: number;
  loadedStr: string;
  status: string;
  error: string;
  abort?: boolean;
  complete?: boolean;
  held?: boolean;
  uploading?: boolean;
}

UploadFileRejectEvent

/**
 * Fired when a file cannot be added to the queue due to a constrain:
 * file-size, file-type or maxFiles
 */
export type UploadFileRejectEvent = UploadEvent<{ file: UploadFile; error: string }>;

UploadFilesChangedEvent

/**
 * Fired when the `files` property changes.
 */
export type UploadFilesChangedEvent = UploadEvent<{ value: UploadFile[] }>;

UploadI18n

export interface UploadI18n {
  dropFiles?: {
    one?: string;
    many?: string;
  };
  addFiles?: {
    one?: string;
    many?: string;
  };
  error?: {
    tooManyFiles?: string;
    fileIsTooBig?: string;
    incorrectFileType?: string;
  };
  uploading?: {
    status?: {
      connecting?: string;
      stalled?: string;
      processing?: string;
      held?: string;
    };
    remainingTime?: {
      prefix?: string;
      unknown?: string;
    };
    error?: {
      serverUnavailable?: string;
      unexpectedServerError?: string;
      forbidden?: string;
    };
  };
  units?: {
    size?: string[];
    sizeBase?: number;
  };

  formatSize?(bytes: number): string;

  formatTime?(seconds: number, units: number[]): string;
}

UploadMaxFilesReachedChangedEvent

/**
 * Fired when the `max-files-reached` property changes.
 */
export type UploadMaxFilesReachedChangedEvent = UploadEvent<{ value: boolean }>;

UploadMethod

export type UploadMethod = 'POST' | 'PUT';