import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import UppyCdnExample from '/src/components/UppyCdnExample'; # Form The `@uppy/form` plugin integrates with an existing HTML `
` 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 `` 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** (``). 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`](#submitOnSuccess) and [`triggerUploadOnSubmit`](#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()`](/docs/uppy#setmetadata) and listen to [`uppy.on('complete')`](/docs/uppy#complete) to get the upload results back. ::: ## Install ```shell npm install @uppy/form ``` ```shell yarn add @uppy/form ``` {` import { Uppy, Form } from "{{UPPY_JS_URL}}" const uppy = new Uppy() uppy.use(Form, { // Options }) `} ## Use ```js title="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', }); ``` ```html title="index.html"
``` 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 `` 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`](#triggerUploadOnSubmit) and [`submitOnSuccess`](#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 `` 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 `
` 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 `` 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`).