Skip to main content

Uppy 4.0 is here: TypeScript rewrite, Google Photos, React hooks, and much more.

Form

The @uppy/form plugin integrates with an existing HTML <form> element to extract input data from it, and send along with the Uppy upload. It then appends the upload result back to the form via a hidden input.

When should I use this?​

When you have an existing HTML <form> element and you would like to:

  • Attach the form input values to the files. This is useful if you want to associate meta data from the form (for example, name, location, id) with the uploaded file, so you can process it on the backend. @uppy/form extracts the input values before uploading/processing files and adds them to Uppy meta data state (uppy.state.meta), as well as and each file’s meta, and appends to the upload in an object with [file input name attribute] -> [file input value] key/values.
  • Upload the files and put the response (such as the file URLs) into a hidden field (<input type="hidden" name="uppyResult">). Then you can POST and handle the form yourself. The appended result is a stringified version of a result returned from calling uppy.upload() or listening to complete event.
  • Automatically start the file upload on submit or submit the form after file upload. This is off by default. See submitOnSuccess and triggerUploadOnSubmit options respectively for details.
note

If you are using a UI framework or library like React, Vue or Svelte, you’ll most likely handle form data there as well, and thus won’t need this plugin. Instead, pass meta data to Uppy via uppy.setMeta() and listen to uppy.on('complete') to get the upload results back.

Install​

npm install @uppy/form

Use​

app.js
import Uppy from '@uppy/core';
import Form from '@uppy/form';
import DragDrop from '@uppy/drag-drop';

import '@uppy/core/dist/style.min.css';
import '@uppy/drag-drop/dist/style.min.css';

new Uppy().use(Form, {
	target: '#my-form',
});
index.html
<form id="my-form" action="/submit" method="get">
	<label for="name">Enter your name: </label>
	<input type="text" name="name" required />

	<label for="dob">Date of birth: </label>
	<input type="date" name="dob" />

	<input type="submit" value="Save" />
</form>

By default the code above will:

  1. Extract meta data from the form #my-form.
  2. Send it with the Uppy upload.
  3. Those fields will then be added to Uppy meta data state (uppy.state.meta) and each file’s meta, and appended as (meta)data to the upload in an object with [file input name attribute] -> [file input value] key/values.
  4. When Uppy completes upload/processing, it will add an <input type="hidden" name="uppyResult"> with the stringified upload result object back to the form.
note

You can disable both of these features, see options below.

tip

@uppy/form can also start Uppy upload automatically once the form is submitted, and even submit the form after the upload is complete. This is off by default. See triggerUploadOnSubmit and submitOnSuccess options below for details.

API​

Options​

id​

A unique identifier for this plugin (string, default: 'Form').

target​

DOM element or CSS selector for the form element (string or Element, default: null).

This is required for the plugin to work.

resultName​

The name attribute for the <input type="hidden"> where the result will be added (string, default: uppyResult).

getMetaFromForm​

Configures whether to extract metadata from the form (boolean, default: true).

When set to true, the Form plugin will extract all fields from a <form> element before upload begins. Those fields will then be added to Uppy meta data state (uppy.state.meta) and each file’s meta, and appended as (meta)data to the upload in an object with [file input name attribute] -> [file input value] key/values.

addResultToForm​

Configures whether to add upload/encoding results back to the form in an <input name="uppyResult" type="hidden"> element (boolean, default: true).

triggerUploadOnSubmit​

Configures whether to start the upload when the form is submitted (boolean, default: false).

When a user submits the form (via a submit button, the Enter key or otherwise), this option will prevent form submission, and instead upload files via Uppy. Then you could:

  • Set submitOnSuccess: true if you need the form to actually be submitted once all files have been uploaded.
  • Listen for uppy.on('complete') event to do something else if the file uploads are all you need. For example, if the form is used for file metadata only.

submitOnSuccess​

Configures whether to submit the form after Uppy finishes uploading/encoding (boolean, default: false).