File Uploader configuration

The configuration settings for the File Uploader should be provided via the uc-config block. This block accepts both attributes and DOM properties.

Refer to the list of pre-defined parameters that are used by default in the repository.

Ensure that the validation rules for the uploader align with the validation rules specified in your project settings.

Basic configuration

1
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/uc-file-uploader-regular.min.css">
2
3
<uc-config
4
  ctx-name="my-uploader"
5
  pubkey="YOUR_PUBLIC_KEY"
6
  img-only="true"
7
  multiple="true"
8
  max-local-file-size-bytes="524288000"
9
  use-cloud-image-editor="true"
10
  source-list="local, url, camera, dropbox"
11
>
12
</uc-config>
13
14
<uc-file-uploader-regular
15
  ctx-name="my-uploader"
16
></uc-file-uploader-regular>

Define the rules that the file uploader should adhere to, and ensure that you include your public key. Refer to the complete list of available options for more details.

Required attributes

Context ctx-name

Context serves as a bridge connecting different custom elements (referred to as “blocks”) on a page. It enables these blocks to share a common state and interact with each other. Additionally, it facilitates the division of multiple uploaders on a single page.

To bind one block to another, you should manually set a context using the ctx-name attribute:

1
<uc-file-uploader-regular ctx-name="MY_CONTEXT"></uc-file-uploader-regular>

The ctx-name attribute is required for all blocks, even if there’s only one block on the page.

Styles

To ensure a visually appealing uploader, including the CSS file is necessary. We employ global styles, therefore, for each type of uploader, the corresponding CSS file should be included separately.

Each solution has its own dedicated CSS file. Here is a table indicating the specific CSS files for each solution:

Here is an example of including CSS file for uc-file-uploader-regular:

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
</script>
7
8
<uc-config
9
  ctx-name="my-uploader"
10
  pubkey="YOUR_PUBLIC_KEY"
11
></uc-config>
12
13
<uc-file-uploader-regular
14
  ctx-name="my-uploader"
15
></uc-file-uploader-regular>

You aren’t restricted to use jsdeliver CDN. You can use any CDN or host the files yourself. Or even use a bundler to handle CSS file as a static asset, for example:

1
import "@uploadcare/file-uploader/web/uc-file-uploader-regular.min.css";
2
import * as UC from "@uploadcare/file-uploader/web/uc-file-uploader-regular.min.js";
3
4
UC.defineComponents(UC);

How to define attributes

Given that HTML attribute values are always strings, only simple data types can be passed, such as strings, numbers, and boolean values.

1
<uc-config
2
  this-is-string="I am a string"
3
  this-is-number="1000"
4
  this-is-boolean="true"
5
>
6
</uc-config>

Passing strings and numbers is pretty straightforward. Boolean values are checked by the following rules:

• true means true (e.g. <uc-config this-is-boolean="true"></uc-config>)
• attribute presence means true (e.g. <uc-config this-is-boolean></uc-config>).
• empty string mean true (e.g. <uc-config this-is-boolean=""></uc-config>).
• any other thruthy value means true (e.g. <uc-config this-is-boolean="value"></uc-config>).
• false means false (e.g. <uc-config this-is-boolean="false"></uc-config>).

Attributes could be defined in both kebab-case and camelCase.

How to define DOM properties

Since HTML attribute values are always strings, you can’t pass complex data like objects or functions. To pass such data, you can use DOM properties. Plain data also works with DOM properties.

Here is an example of passing an object and function in vanilla JS:

1
const config = document.querySelector('uc-config')
2
3
config.metadata = {
4
  myCustomData: 'myValue'
5
}
6
7
config.metadata = () => ({
8
  myCustomData: 'myValue'
9
})

DOM properties could be defined in camelCase only.

Frameworks

If you’re using a framework, you can set DOM properties in a framework-specific way.

For example, in Vue 3, you can use native binding syntax; it will work out of the box. See Vue and Web Components for more details.

With React, you can use ref to get a reference to the element and set DOM properties on it. The native binding syntax will be supported in React 19. See RFC: Plan for custom element attributes/properties in React 19 for more details.

Reactivity

Both attributes and DOM properties are reactive. It means that if you change the value of an attribute or DOM property, the uploader will be updated automatically.