File Uploader HTML forms handling

We provide the dedicated element uc-form-input to handle HTML forms with the File Uploader. This is useful when you use the File Uploader within the HTML form with the native client-side (browser) validation.

In the case of rich-featured forms with custom validation and inline errors rendering, it’s better to use directly Events and/or API to extract data from the File Uploader.

Usage

The only attribute that uc-form-input tag requires is ctx-name, see Context for more details.

It could be placed anywhere on the page. However, we recommend placing it inside the File Uploader to make it able to align native validation messages within the File Uploader button.

It supports two modes:

• Multiple separate inputs for each file.
• Single input for the group of files.

The current mode is defined by the group-output attribute on the uc-config tag.

Separate inputs for each file

In this mode, each file will be represented by its own input. It is useful when you need to handle each file separately.

Every input will have the name of the ctx-name attribute with the [] suffix.

Here is the example of the output FormData entries:

1
[
2
  ["my-uploader[]", "https://ucarecdn.com/:uuid/"],
3
  ["my-uploader[]", "https://ucarecdn.com/:uuid/"]
4
]

In the example above, my-uploader is the ctx-name attribute value.

One input for the group of files

In this mode, all files will be represented by a single input. It is useful when you need to handle all files as a group.

The input will have the name of the ctx-name.

Here is the example of the output FormData entries:

1
[["my-uploader", "https://ucarecdn.com/:uuid~2/"]]

In the example above, my-uploader is the ctx-name attribute value.

Configuration

As it was mentioned above, the only attribute that uc-form-input tag accepts and requires is ctx-name.

But it also relies on a few attributes of the uc-config tag:

• group-output - defines the behaviour mode (single input for the group of files or multiple inputs for each file).
• multiple-min - if it is greater than 0, the input will be required, preventing the form from submitting until the required number of files is uploaded.

Example

Here is the example of the HTML form with the File Uploader:

1
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/uc-file-uploader-regular.min.css">
2
3
 <script type="module">
4
  import * as UC from "https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/uc-file-uploader-regular.min.js";
5
  UC.defineComponents(UC);
6
  const form = document.querySelector("form");
7
  form.addEventListener("submit", (e) => {
8
    e.preventDefault();
9
    const form = e.target;
10
    const formData = new FormData(form);
11
    const outputEl = document.querySelector("#form-output");
12
    outputEl.innerText = JSON.stringify([...formData.entries()], null, 2);
13
  });
14
</script>
15
16
<style>
17
  uc-file-uploader-regular {
18
    position: relative;
19
    display: inline-block;
20
  }
21
  uc-form-input {
22
    position: absolute;
23
    bottom: 0px;
24
    left: 50%;
25
  }
26
</style>
27
28
<uc-config
29
  ctx-name="my-uploader"
30
  pubkey="YOUR_PUBLIC_KEY"
31
  multiple
32
  multiple-min="2"
33
  multiple-max="3"
34
  img-only
35
  group-output
36
></uc-config>
37
38
<form>
39
  <label for="name">Name:</label><br />
40
  <input type="text" id="fname" name="fname" value="John" />
41
42
  <uc-file-uploader-regular
43
    ctx-name="my-uploader"
44
  >
45
    <uc-form-input ctx-name="my-uploader"></uc-form-input>
46
  </uc-file-uploader-regular>
47
48
  <button type="submit">Submit</button>
49
50
  <code>
51
    <pre id="form-output"></pre>
52
  </code>
53
</form>

Get YOUR_PUBLIC_KEY from API keys.