---
title: Upload
description: Upload
element: vaadin-upload
---

## Description

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

Example:

```html
<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
---------------------|---------------------------------
`disabled`           | Set when the element is disabled
`nodrop`             | Set when drag and drop is disabled (e.g., on touch devices)
`dragover`           | Set when the file is being dragged over the element
`dragover-valid`     | Set when the dragged file is valid with `maxFiles` and `accept` criteria
`max-files-reached`  | Set when maximum number of files that the user is allowed to add has been reached

The following custom CSS properties are available for styling:

Custom CSS property                          |
:--------------------------------------------|
`--vaadin-upload-background`                 |
`--vaadin-upload-border-color`               |
`--vaadin-upload-border-radius`              |
`--vaadin-upload-border-width`               |
`--vaadin-upload-gap`                        |
`--vaadin-upload-padding`                    |
`--vaadin-upload-drop-label-color`           |
`--vaadin-upload-drop-label-font-size`       |
`--vaadin-upload-drop-label-font-weight`     |
`--vaadin-upload-drop-label-gap`             |
`--vaadin-upload-drop-label-line-height`     |
`--vaadin-upload-file-list-divider-color`    |
`--vaadin-upload-file-list-divider-width`    |
`--vaadin-upload-file-border-radius`         |
`--vaadin-upload-file-button-background`     |
`--vaadin-upload-file-button-border-color`   |
`--vaadin-upload-file-button-border-radius`  |
`--vaadin-upload-file-button-border-width`   |
`--vaadin-upload-file-button-text-color`     |
`--vaadin-upload-file-button-padding`        |
`--vaadin-upload-file-done-color`            |
`--vaadin-upload-file-error-color`           |
`--vaadin-upload-file-error-font-size`       |
`--vaadin-upload-file-error-font-weight`     |
`--vaadin-upload-file-error-line-height`     |
`--vaadin-upload-file-gap`                   |
`--vaadin-upload-file-name-color`            |
`--vaadin-upload-file-name-font-size`        |
`--vaadin-upload-file-name-font-weight`      |
`--vaadin-upload-file-name-line-height`      |
`--vaadin-upload-file-padding`               |
`--vaadin-upload-file-status-color`          |
`--vaadin-upload-file-status-font-size`      |
`--vaadin-upload-file-status-font-weight`    |
`--vaadin-upload-file-status-line-height`    |
`--vaadin-upload-file-warning-color`         |

See [Styling Components](https://vaadin.com/docs/latest/styling/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`](https://developer.mozilla.org/en-US/docs/Web/API/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](#uploadfile)

### formDataName

**Type:** `string`

Specifies the 'name' property at Content-Disposition for multipart uploads.
This property is ignored when uploadFormat is 'raw'.

### 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:
```html
<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:

```js
{
  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](#uploadi18n)

### maxConcurrentUploads

**Type:** `number`

Specifies the maximum number of files that can be uploaded simultaneously.
This helps prevent browser performance degradation and XHR limitations when
uploading large numbers of files. Files exceeding this limit will be queued
and uploaded as active uploads complete.

### 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](#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.

### uploadFormat

**Type:** `UploadFormat`

Specifies the upload format to use when sending files to the server.
- 'raw': Send file as raw binary data with the file's MIME type as Content-Type (default)
- 'multipart': Send file using multipart/form-data encoding

See also: [UploadFormat](#uploadformat)

### 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](#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](#uploadfileschangedevent)

Fired when the `files` property changes.

### max-files-reached-changed

**Type:** [UploadMaxFilesReachedChangedEvent](#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

```ts
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

```ts
/**
 * 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

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

### UploadFormat

```ts
export type UploadFormat = 'raw' | 'multipart';
```

### UploadI18n

```ts
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;
      fileTooLarge?: string;
    };
  };
  units?: {
    size?: string[];
    sizeBase?: number;
  };

  formatSize?(bytes: number): string;

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

### UploadMaxFilesReachedChangedEvent

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

### UploadMethod

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