> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: $w

## Namespace: upload-button

## Article: Introduction

## Article Link: https://dev.wix.com/docs/velo/velo-only-apis/$w/upload-button/introduction.md

## Article Content:

# Introduction
<blockquote class="important">

__Important:__

The upload button was recently updated. You can see updates to the upload button [here](#updates-to-the-upload-button).
</blockquote>

 When adding an upload button to a site, you generally also add a regular button. The upload button allows a site visitor to add the files they want to upload, and the regular button triggers the actual upload of the files to the site.
 The following describes the flow for a typical file upload scenario:

 ### Typical File Upload Scenario

 1. The site visitor clicks the upload button, and chooses which files to upload by selecting the files in a native file chooser dialog. 
 1. At that point, the selected files are stored in the upload button's `value` property as an array of `File` objects. 
 1. The [`onChange()`]($w/upload-button/on-change) event is triggered.
 1. Validations on the files are performed, following which the [`valid`]($w/upload-button/valid), [`validity`]($w/upload-button/validity), and [`validationMessage`]($w/upload-button/validation-message) properties are updated. Because `onChange()` is fired before validations are performed, do not check any of the validation properties in the code of the `onChange()` event handler. For example, do not code an `if` statement that checks the `valid` property in the `onChange()` because the property at this point contains values prior to the `onChange()`.
 1. The site visitor clicks the regular button. 
 1. The regular button's `onClick()` event handler calls the [`uploadFiles()`](/$w/upload-button/upload-files) function. This function triggers the actual upload of the files stored in the upload button's [`value`]($w/upload-button/value) property. 
 1. The upload either succeeds and returns an `UploadedFile` object, or fails and returns an `UploadError` object.

 See the code example in the [`uploadFiles()`]($w/upload-button/upload-files) function for the typical file upload scenario. 

> **Note:** 
> The `onChange()` event is triggered before validation. As a result, consider the following points if you intend
  to call the `uploadFiles` function inside the `onChange()` event handler: 
> + `uploadFiles()` returns promptly with an `UploadError` object if the `fileSizeExceedsLimit`or `fileTypeNotAllowed` validity property is true. 
> + If the validation fails for one of these reasons, causing an error to be returned, the `uploadFiles()` function doesn't attempt the upload.


 ### Updates to the Upload Button
  + The [`startUpload()`]($w/upload-button/start-upload) function, which allows you to upload 1 file at a time, is deprecated. The function will continue to work, but a new and updated [`uploadFiles()`]($w/upload-button/upload-files) function is available instead. With `uploadFiles()`, you can upload multiple files at the same time.
  + The `value` property returns 2 additional parameters, `valid` and `validationMessage`. 
  + The `fileType` property has an additional `Gallery` value that accepts both images and videos at the same time. 
  + The `validity` property has an additional `exceedsFileLimit` validity message in the `ValidityState` object.
  + The upload button has an additional `.fileLimit` property that gets/sets the maximum amount of files a site vistor can upload at a time.